/ Hex Artifact Content
Login

Artifact fdf272c7bb095633d3f5f916cf7384c4faa505e5:


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 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.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 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
42b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
42c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
42d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
42e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
42f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4320: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4330: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4340: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4350: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4360: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4370: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4380: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
43a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
43b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
43c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
43d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
43e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
43f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4400: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4420: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4430: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4440: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4460: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4470: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4480: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4490: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
44a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
44b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
44c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
44d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
44f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4500: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4510: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4530: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4540: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4550: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4560: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4580: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4590: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
45a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
45b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
45d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
45e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
45f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4600: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4610: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4620: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4630: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4640: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4650: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4660: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4680: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4690: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
46a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
46b0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
46c0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
46e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4700: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4710: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4720: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4730: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4740: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4750: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4760: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4770: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4780: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4790: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
47a0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
47b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
47c0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
47d0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
47e0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
47f0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4800: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4810: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4820: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4830: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4840: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4850: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4860: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4870: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4880: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4890: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
48a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
48b0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
48c0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
48d0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
48e0: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
48f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4900: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4910: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4920: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4930: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4940: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4950: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4960: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4970: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4980: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
4990: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49a0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
49b0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
49c0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
49d0: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
49e0: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
49f0: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4a00: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4a10: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4a30: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4a40: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4a50: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
4a70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
4a80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
4a90: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
4aa0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
4ab0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
4ac0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4ad0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
4ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4b30: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4b70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4bf0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
4d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d60: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
4d70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d80: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4da0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
4db0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4dc0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4de0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
4df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e00: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e20: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
4e30: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
4e40: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e60: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
4e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e80: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ea0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
4eb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4ec0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ee0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
4ef0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f00: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4f20: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4f30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4f40: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4f50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4f60: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4f70: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
4f80: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
4f90: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
4fa0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
4fb0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
4fc0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
4fd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
4fe0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4ff0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
5000: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
5010: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
5020: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
5030: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5040: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5050: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5060: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5070: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5080: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5090: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
50a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
50b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
50c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
50d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
50f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5100: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5110: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5120: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5140: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5150: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
5160: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5180: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5190: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
51a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
51c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
51d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
51e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5200: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5210: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
5220: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5240: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5250: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
5260: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5280: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
5290: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
52a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
52c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
52d0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
52e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5300: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5310: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
5320: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5350: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
5360: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5380: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5390: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
53a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
53c0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
53d0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
53e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
53f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5410: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5420: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
5430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5460: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5470: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
5480: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5490: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
54b0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
54c0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
54d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
54e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a  en_v2() */../*.*
54f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5500: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5510: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
5520: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73  viceCapabilities
5530: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
5540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5550: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
5560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
5570: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
5580: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
5590: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
55a0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
55b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
55c0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
55d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
55e0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
55f0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
5600: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5610: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
5620: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5630: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5640: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5650: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5660: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5670: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5680: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5690: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
56a0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
56b0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
56c0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
56d0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
56e0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
56f0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5700: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5710: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5720: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5740: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5750: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5760: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5770: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5780: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5790: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
57a0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
57b0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
57c0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
57d0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
57e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
57f0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5800: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5810: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5820: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5830: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5840: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5850: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5870: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
5880: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58a0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
58b0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58d0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
58e0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5900: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5910: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5930: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5940: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5960: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5970: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5990: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
59a0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59c0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
59d0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59f0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5a00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
5a30: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a50: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
5a60: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
5a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5a80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5a90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5aa0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5ab0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5ac0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5ad0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ae0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5af0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5b00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5b10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5b70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5b90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5ba0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5bc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5bd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5be0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5c00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5c10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5c20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5c30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5c40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5c50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5c70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5c80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5c90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ca0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5cb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5cd0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ce0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5cf0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5d00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5d10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5d20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5d30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5d40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5d50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5d60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5d70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5d80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5d90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5da0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5db0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5dc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5de0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5df0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
5e00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5e10: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5e20: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5e30: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5e50: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5e60: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5e80: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5e90: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5ea0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5eb0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
5ec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5ed0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5ee0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
5ef0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5f00: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5f10: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5f20: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
5f30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
5f40: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5f50: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
5f60: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
5f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
5f80: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
5f90: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
5fa0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
5fb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5fc0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5fd0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5fe0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5ff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6010: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6020: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6030: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6040: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6050: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6060: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6070: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6080: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6090: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
60a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
60b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
60c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
60d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
60e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
60f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6100: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6110: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6120: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6130: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6140: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6170: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6190: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
61a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
61b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
61c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
61d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
61e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
61f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6200: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6220: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6230: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6240: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6250: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6260: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6280: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6290: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
62a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
62b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
62c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
62d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
62e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6300: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6310: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6320: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6330: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6340: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6350: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6360: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6370: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6380: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6390: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
63a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
63b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
63c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
63d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
63e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
63f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6400: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6410: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6420: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6430: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6440: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6450: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6460: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6470: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6480: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6490: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
64a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
64b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
64c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
64d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
64e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
64f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6500: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6510: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6520: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6530: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6540: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6550: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6590: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
65a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
65c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
65f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6600: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6610: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6620: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6630: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6640: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6650: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6660: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6670: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6690: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
66a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
66b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
66c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
66d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
66e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
66f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6700: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6710: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6720: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6730: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6740: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6750: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6760: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6770: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6780: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6790: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
67a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
67b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
67c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
67d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
67e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
67f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6800: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6810: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6820: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6830: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6840: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6850: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6870: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6880: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6890: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
68a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
68b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
68c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
68d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
68e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
68f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6900: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6910: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6920: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6930: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6940: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6950: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6960: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6970: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6980: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6990: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
69a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
69b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
69c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
69d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
69e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
69f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6a00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6a10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6a20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6a30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6a40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6a50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6a60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6a70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6a80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6a90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6aa0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6ac0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6ad0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ae0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6af0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6b00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6b10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6b20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6b30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6b40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6b50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6b60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6b70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6b80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6b90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6ba0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6bb0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6bc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6bd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6be0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6bf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6c00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6c10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6c30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6c60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ce0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6d40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6d70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6d80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6d90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6da0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6db0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6dc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6de0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6df0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6e00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6e10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6e20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6e30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6e40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6e50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6e60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6e70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6e80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6e90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6ea0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6eb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6ec0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6ed0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ee0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6ef0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6f00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6f10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6f20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6f40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6f50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6f60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6f70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6f80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6f90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6fa0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
6fb0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
6fc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
6fd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
6fe0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
6ff0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7000: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7010: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7020: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7030: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7040: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7050: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7060: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7070: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7080: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7090: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
70a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
70b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
70c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
70d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
70e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
70f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7120: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7130: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7140: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7150: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7160: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7170: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7180: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7190: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
71a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
71b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
71d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
71e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
71f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7200: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7210: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7220: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7240: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7250: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7260: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7270: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7280: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
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 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
72d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
72f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7300: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7310: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7320: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7330: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7340: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7350: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7360: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7380: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
7390: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
73a0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
73b0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
73c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
73d0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
73e0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
73f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
7400: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
7410: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
7420: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7430: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
7440: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7450: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
7460: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
7470: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
7480: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
7490: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
74a0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
74b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
74c0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
74d0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
74e0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
74f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
7500: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
7510: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
7520: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
7530: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7540: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
7550: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
7560: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7570: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
7580: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
7590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
75a0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
75b0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
75c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
75d0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
75e0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
75f0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
7600: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
7610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
7620: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
7630: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
7640: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
7650: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
7660: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
7670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7680: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
7690: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
76a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
76b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
76c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
76d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
76e0: 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20         4../*.** 
76f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
7700: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
7710: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
7720: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
7730: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
7740: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
7750: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
7760: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
7770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
7780: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
7790: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
77a0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
77b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
77c0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
77d0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
77e0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
77f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
7800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
7810: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
7820: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
7830: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
7840: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7850: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
7860: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
7870: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7880: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
7890: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
78a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
78b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
78c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
78d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
78e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
78f0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
7900: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
7910: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
7920: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
7930: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
7940: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
7950: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
7960: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
7970: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
7980: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
7990: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
79a0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
79b0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
79c0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
79d0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
79e0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
79f0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
7a00: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
7a10: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
7a20: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
7a30: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
7a40: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
7a50: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
7a60: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
7a70: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
7a80: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
7a90: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
7aa0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
7ab0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
7ac0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
7ad0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7ae0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7af0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7b00: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7b10: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7b20: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7b30: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7b40: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7b50: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7b60: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7b70: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7b80: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7b90: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7ba0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
7bb0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
7bc0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7bd0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7be0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7bf0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7c00: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7c10: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7c20: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7c30: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7c40: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7c50: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7c60: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7c70: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7c80: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
7c90: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
7ca0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
7cb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
7cc0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
7cd0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
7ce0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
7cf0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
7d00: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
7d10: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
7d20: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
7d30: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
7d40: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
7d50: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
7d60: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
7d70: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
7d80: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
7d90: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
7da0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
7db0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
7dc0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
7dd0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
7de0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
7df0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
7e00: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
7e10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
7e20: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
7e30: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
7e40: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
7e50: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
7e60: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
7e70: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
7e80: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
7e90: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7ea0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
7eb0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
7ec0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
7ed0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
7ee0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
7ef0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
7f00: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7f10: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7f20: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7f30: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7f40: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7f50: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7f60: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
7f70: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
7f80: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
7f90: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
7fa0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
7fb0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
7fc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
7fd0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
7fe0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
7ff0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
8000: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
8010: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
8020: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
8030: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8040: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
8050: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
8060: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
8070: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
8080: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
8090: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
80a0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
80b0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
80c0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
80d0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
80e0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
80f0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8100: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8110: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8120: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8130: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8140: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8150: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8160: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8170: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8190: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
81a0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
81b0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
81c0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
81d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
81e0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
81f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8200: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
8210: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8220: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8230: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8240: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8260: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8270: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8280: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8290: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
82a0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
82b0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
82c0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
82d0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
82e0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
82f0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
8300: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8310: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8320: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
8330: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8340: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
8350: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8360: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
8370: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8380: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8390: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
83b0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
83c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
83d0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
83e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
83f0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
8400: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
8410: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
8420: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
8430: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
8440: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
8450: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8460: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8470: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8480: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
8490: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
84a0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
84b0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
84c0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
84d0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
84e0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
84f0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
8500: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
8510: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
8520: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
8530: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
8540: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
8550: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8560: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8570: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8580: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
8590: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
85a0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
85b0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
85c0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
85d0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
85e0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
85f0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
8600: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
8610: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
8620: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
8630: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8640: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8650: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8660: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8670: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8690: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
86a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
86b0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
86c0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
86e0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
86f0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
8700: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
8710: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
8720: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
8730: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8740: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
8750: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
8760: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
8770: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
8780: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
8790: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
87a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
87b0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
87c0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
87d0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
87e0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
87f0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
8800: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
8810: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
8820: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
8830: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
8840: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
8850: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
8860: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
8870: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
8880: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
8890: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
88a0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
88b0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
88c0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
88d0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
88e0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
88f0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
8900: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
8910: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
8920: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
8930: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8940: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
8950: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8960: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
8970: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
8980: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
8990: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
89a0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
89b0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
89c0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
89d0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
89e0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
89f0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
8a00: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
8a10: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
8a20: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
8a30: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
8a40: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
8a50: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
8a60: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
8a70: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
8a80: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
8a90: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
8aa0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
8ab0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8ac0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
8ad0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
8ae0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
8af0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
8b00: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8b10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8b20: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8b30: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8b40: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
8b50: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
8b60: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
8b70: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
8b80: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
8b90: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
8ba0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
8bb0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
8bc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
8bd0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
8be0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
8bf0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
8c00: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
8c10: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
8c20: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
8c30: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8c40: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8c50: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8c60: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8c70: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8c80: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8c90: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
8ca0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
8cb0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
8cc0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
8cd0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
8ce0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
8cf0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
8d00: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
8d10: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8d20: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8d30: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8d40: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8d50: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8d60: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8d70: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
8d80: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8d90: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8da0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8db0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8dc0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8dd0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8de0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8df0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8e00: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8e10: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8e20: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8e30: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8e40: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8e50: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8e60: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8e70: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8e80: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8e90: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8ea0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
8eb0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
8ec0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
8ed0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
8ee0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
8ef0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
8f00: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8f10: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8f20: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8f30: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8f40: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8f50: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8f60: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8f70: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8f80: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8f90: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8fa0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
8fb0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
8fc0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
8fd0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
8fe0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
8ff0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
9000: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
9010: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
9020: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
9030: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
9040: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
9050: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
9060: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
9070: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
9080: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
9090: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
90a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
90b0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
90c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
90d0: 71 6c 69 74 65 33 5f 73 68 6d 20 73 71 6c 69 74  qlite3_shm sqlit
90e0: 65 33 5f 73 68 6d 3b 0a 73 74 72 75 63 74 20 73  e3_shm;.struct s
90f0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
9100: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
9110: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
9120: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
9130: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 32  ber (currently 2
9140: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
9150: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
9160: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
9170: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
9180: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
9190: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
91a0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
91b0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
91c0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
91d0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
91e0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
91f0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
9200: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
9210: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
9220: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
9230: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
9240: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
9250: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
9260: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
9270: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
9280: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
9290: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
92a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
92b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
92c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
92d0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
92e0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
92f0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
9300: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9310: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9320: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
9330: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
9340: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9350: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9360: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
9370: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
9380: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
9390: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
93a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
93b0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
93c0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
93d0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
93e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
93f0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
9400: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
9410: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9420: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
9430: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
9440: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
9450: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
9460: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
9470: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
9480: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
9490: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
94a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
94b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
94d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
94e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
94f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
9500: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
9510: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
9520: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
9530: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
9540: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
9550: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
9560: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
9570: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
9580: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
9590: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
95a0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
95b0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
95c0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
95d0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
95e0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
95f0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
9600: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
9610: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
9620: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9630: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
9640: 68 6d 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  hm**);.  int (*x
9650: 53 68 6d 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ShmSize)(sqlite3
9660: 5f 73 68 6d 2a 2c 20 69 6e 74 20 72 65 71 53 69  _shm*, int reqSi
9670: 7a 65 2c 20 69 6e 74 20 2a 70 4e 65 77 53 69 7a  ze, int *pNewSiz
9680: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  e);.  int (*xShm
9690: 47 65 74 29 28 73 71 6c 69 74 65 33 5f 73 68 6d  Get)(sqlite3_shm
96a0: 2a 2c 20 69 6e 74 20 72 65 71 4d 61 70 53 69 7a  *, int reqMapSiz
96b0: 65 2c 20 69 6e 74 20 2a 70 4d 61 70 53 69 7a 65  e, int *pMapSize
96c0: 2c 20 76 6f 69 64 2a 2a 29 3b 0a 20 20 69 6e 74  , void**);.  int
96d0: 20 28 2a 78 53 68 6d 52 65 6c 65 61 73 65 29 28   (*xShmRelease)(
96e0: 73 71 6c 69 74 65 33 5f 73 68 6d 2a 29 3b 0a 20  sqlite3_shm*);. 
96f0: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
9700: 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a 2c 20 69  (sqlite3_shm*, i
9710: 6e 74 20 64 65 73 69 72 65 64 4c 6f 63 6b 2c 20  nt desiredLock, 
9720: 69 6e 74 20 2a 67 6f 74 4c 6f 63 6b 29 3b 0a 20  int *gotLock);. 
9730: 20 69 6e 74 20 28 2a 78 53 68 6d 43 6c 6f 73 65   int (*xShmClose
9740: 29 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a 29 3b  )(sqlite3_shm*);
9750: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 44 65 6c  .  int (*xShmDel
9760: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
9770: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9780: 4e 61 6d 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Name);.  int (*x
9790: 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  Rename)(sqlite3_
97a0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
97b0: 20 2a 7a 4f 6c 64 2c 20 63 6f 6e 73 74 20 63 68   *zOld, const ch
97c0: 61 72 20 2a 7a 4e 65 77 2c 20 69 6e 74 20 64 69  ar *zNew, int di
97d0: 72 53 79 6e 63 29 3b 0a 20 20 69 6e 74 20 28 2a  rSync);.  int (*
97e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
97f0: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
9800: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
9810: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
9820: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
9830: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
9840: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
9850: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
9860: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
9870: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
9880: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
9890: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
98a0: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
98b0: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
98c0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
98d0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
98e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
98f0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
9900: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
9910: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
9920: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
9930: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
9940: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
9950: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
9960: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
9970: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
9980: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
9990: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
99a0: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
99b0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
99c0: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
99d0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
99e0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
99f0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9a00: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
9a10: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
9a20: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
9a30: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
9a40: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
9a50: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
9a60: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
9a70: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
9a80: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
9a90: 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57  d writable..** W
9aa0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
9ab0: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
9ac0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
9ad0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
9ae0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
9af0: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
9b00: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
9b10: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
9b20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
9b30: 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e  ADWRITE 1.#defin
9b40: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
9b50: 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a  READ      2../*.
9b60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
9b70: 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
9b80: 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
9b90: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
9ba0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
9bb0: 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
9bc0: 6c 6f 63 6b 69 6e 67 20 73 74 61 74 65 73 20 74  locking states t
9bd0: 68 61 74 0a 2a 2a 20 61 6e 20 73 71 6c 69 74 65  hat.** an sqlite
9be0: 33 5f 73 68 6d 20 6f 62 6a 65 63 74 20 63 61 6e  3_shm object can
9bf0: 20 62 65 20 69 6e 2e 20 20 54 68 65 20 53 51 4c   be in.  The SQL
9c00: 49 54 45 5f 53 48 4d 5f 51 55 45 52 59 20 69 6e  ITE_SHM_QUERY in
9c10: 74 65 67 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  teger.** is not 
9c20: 61 20 76 61 6c 69 64 20 64 61 74 61 20 2d 20 69  a valid data - i
9c30: 74 20 69 73 20 61 20 63 6f 6e 73 74 61 6e 74 20  t is a constant 
9c40: 70 61 73 74 65 64 20 74 6f 20 74 68 65 20 0a 2a  pasted to the .*
9c50: 2a 20 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 53  * sqlite3_vfs.xS
9c60: 68 6d 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  hmLock() method 
9c70: 66 6f 72 20 71 75 65 72 79 69 6e 67 20 74 68 65  for querying the
9c80: 20 63 75 72 72 65 6e 74 20 6c 6f 63 6b 0a 2a 2a   current lock.**
9c90: 20 73 74 61 74 65 2e 0a 2a 2f 0a 23 64 65 66 69   state..*/.#defi
9ca0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
9cb0: 4c 4f 43 4b 20 20 20 20 20 20 20 30 0a 23 64 65  LOCK       0.#de
9cc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
9cd0: 52 45 41 44 20 20 20 20 20 20 20 20 20 31 0a 23  READ         1.#
9ce0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
9cf0: 4d 5f 52 45 41 44 5f 46 55 4c 4c 20 20 20 20 32  M_READ_FULL    2
9d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9d10: 53 48 4d 5f 57 52 49 54 45 20 20 20 20 20 20 20  SHM_WRITE       
9d20: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
9d30: 45 5f 53 48 4d 5f 50 45 4e 44 49 4e 47 20 20 20  E_SHM_PENDING   
9d40: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
9d50: 49 54 45 5f 53 48 4d 5f 43 48 45 43 4b 50 4f 49  ITE_SHM_CHECKPOI
9d60: 4e 54 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53  NT   5.#define S
9d70: 51 4c 49 54 45 5f 53 48 4d 5f 52 45 43 4f 56 45  QLITE_SHM_RECOVE
9d80: 52 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65  R      6.#define
9d90: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 51 55 45 52   SQLITE_SHM_QUER
9da0: 59 20 20 20 20 20 20 20 20 28 2d 31 29 0a 0a 2f  Y        (-1)../
9db0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
9dc0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
9dd0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
9de0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
9df0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
9e00: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
9e10: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
9e20: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
9e30: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9e40: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
9e50: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
9e60: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
9e70: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
9e80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9e90: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
9ea0: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
9eb0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
9ec0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
9ed0: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
9ee0: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
9ef0: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
9f00: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
9f10: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
9f20: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
9f30: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
9f40: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
9f50: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
9f60: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
9f70: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9f80: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
9f90: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
9fa0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
9fb0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9fc0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
9fd0: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
9fe0: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
9ff0: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
a000: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
a010: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
a020: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
a030: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
a040: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
a050: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
a060: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
a070: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
a080: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a090: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
a0a0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
a0b0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
a0c0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
a0d0: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
a0e0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
a0f0: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
a100: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
a110: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
a120: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
a130: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a140: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
a150: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
a160: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
a170: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
a180: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
a190: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
a1a0: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
a1b0: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
a1c0: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
a1d0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
a1e0: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
a1f0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
a200: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
a210: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
a220: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
a230: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
a240: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
a250: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
a260: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
a270: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
a280: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
a290: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
a2a0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
a2b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a2c0: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
a2d0: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
a2e0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
a2f0: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
a300: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
a310: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
a320: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a330: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
a340: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
a350: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a360: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
a370: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
a380: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
a390: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
a3a0: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
a3b0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
a3c0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
a3d0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
a3e0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
a3f0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a400: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
a410: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
a420: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
a430: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
a440: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
a450: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
a460: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
a470: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
a480: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
a490: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
a4a0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
a4b0: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
a4c0: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
a4d0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
a4e0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
a4f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
a500: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
a510: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
a520: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
a530: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
a540: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
a550: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
a560: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
a570: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
a580: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
a590: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
a5a0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
a5b0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
a5c0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a5d0: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
a5e0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
a5f0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
a600: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
a610: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
a620: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
a630: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
a640: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
a650: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
a660: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
a670: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
a680: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
a690: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
a6a0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
a6b0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
a6c0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
a6d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a6e0: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
a6f0: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
a700: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
a710: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a720: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
a730: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
a740: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
a750: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
a760: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
a770: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
a780: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
a790: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
a7a0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
a7b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
a7c0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
a7d0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
a7e0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
a7f0: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
a800: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
a810: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
a820: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
a830: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
a840: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
a850: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
a860: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
a870: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
a880: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
a890: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
a8a0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
a8b0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
a8c0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
a8d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
a8e0: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
a8f0: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
a900: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
a910: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
a920: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
a930: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
a940: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a950: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
a960: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
a970: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
a980: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
a990: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
a9a0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
a9b0: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
a9c0: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
a9d0: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
a9e0: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
a9f0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
aa00: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
aa10: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
aa20: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
aa30: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
aa40: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
aa50: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
aa60: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
aa70: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
aa80: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
aa90: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
aaa0: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
aab0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
aac0: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
aad0: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
aae0: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
aaf0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
ab00: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
ab10: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
ab20: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
ab30: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
ab40: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
ab50: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
ab60: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
ab70: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
ab80: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
ab90: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
aba0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
abb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
abc0: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
abd0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
abe0: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
abf0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
ac00: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
ac10: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
ac20: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
ac30: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
ac40: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
ac50: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
ac60: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
ac70: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
ac80: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
ac90: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
aca0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
acb0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
acc0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
acd0: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
ace0: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
acf0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
ad00: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
ad10: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
ad20: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
ad30: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
ad40: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
ad50: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
ad60: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
ad70: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
ad80: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
ad90: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
ada0: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
adb0: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
adc0: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
add0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
ade0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
adf0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
ae00: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
ae10: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
ae20: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
ae30: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
ae40: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
ae50: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
ae60: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
ae70: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
ae80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
ae90: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
aea0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
aeb0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
aec0: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
aed0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
aee0: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
aef0: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
af00: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
af10: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
af20: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
af30: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
af40: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
af50: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
af60: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
af70: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
af80: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
af90: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
afa0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
afb0: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
afc0: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
afd0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
afe0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
aff0: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
b000: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
b010: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
b020: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
b030: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
b040: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
b050: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
b060: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
b070: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
b080: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
b090: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
b0a0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
b0b0: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
b0c0: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
b0d0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
b0e0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
b0f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
b100: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
b110: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
b120: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
b130: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b140: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
b150: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
b160: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
b170: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
b180: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
b190: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
b1a0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
b1b0: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
b1c0: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
b1d0: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
b1e0: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
b1f0: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
b200: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
b210: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
b220: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
b230: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
b240: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
b250: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
b260: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
b270: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
b280: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
b290: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
b2a0: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
b2b0: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
b2c0: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
b2d0: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
b2e0: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
b2f0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
b300: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
b310: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  n the [SQLITE_CO
b320: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
b330: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
b340: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
b350: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
b360: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
b370: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
b380: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
b390: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
b3a0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
b3b0: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
b3c0: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
b3d0: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
b3e0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
b3f0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
b400: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
b410: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
b420: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
b430: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
b440: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
b450: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b460: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
b470: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
b480: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
b490: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
b4a0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
b4b0: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
b4c0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
b4d0: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
b4e0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
b4f0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
b500: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
b510: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
b520: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
b530: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
b540: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
b550: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
b560: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
b570: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
b580: 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  nt).  The.** sql
b590: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
b5a0: 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c   interface shoul
b5b0: 64 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69  d only be used i
b5c0: 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
b5d0: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
b5e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
b5f0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
b600: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a  lite3_open()],.*
b610: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
b620: 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  6()], or [sqlite
b630: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a  3_open_v2()].  .
b640: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
b650: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
b660: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
b670: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
b680: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
b690: 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67   verb - an integ
b6a0: 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64  er code that ind
b6b0: 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61  icates what.** a
b6c0: 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
b6d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b6e0: 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
b6f0: 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f  igured..** The o
b700: 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74  nly choice for t
b710: 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51  his value is [SQ
b720: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
b730: 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77  OKASIDE]..** New
b740: 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c   verbs are likel
b750: 79 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e  y to be added in
b760: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
b770: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41   of SQLite..** A
b780: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
b790: 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68  nts depend on th
b7a0: 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  e verb..**.** ^C
b7b0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
b7c0: 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
b7d0: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
b7e0: 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
b7f0: 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
b800: 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
b810: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
b820: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
b830: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
b840: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
b850: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
b860: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
b870: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
b880: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
b890: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
b8a0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
b8b0: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
b8c0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
b8d0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
b8e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
b8f0: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
b900: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
b910: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
b920: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
b930: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
b940: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
b950: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
b960: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
b970: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
b980: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
b990: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
b9a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
b9b0: 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
b9c0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
b9d0: 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
b9e0: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
b9f0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
ba00: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
ba10: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
ba20: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
ba30: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
ba40: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
ba50: 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
ba60: 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
ba70: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
ba80: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
ba90: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
baa0: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
bab0: 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
bac0: 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
bad0: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
bae0: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
baf0: 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
bb00: 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
bb10: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
bb20: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
bb30: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
bb40: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
bb50: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
bb60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
bb70: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
bb80: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
bb90: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
bba0: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
bbb0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
bbc0: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
bbd0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
bbe0: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
bbf0: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
bc00: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
bc10: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
bc20: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
bc30: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
bc40: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
bc50: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
bc60: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
bc70: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
bc80: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
bc90: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
bca0: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
bcb0: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
bcc0: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
bcd0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
bce0: 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72   xMalloc and xFr
bcf0: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
bd00: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
bd10: 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
bd20: 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
bd30: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
bd40: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
bd50: 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68  he xRealloc meth
bd60: 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  od must work lik
bd70: 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d  e realloc() from
bd80: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
bd90: 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20  library.** with 
bda0: 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68  the exception th
bdb0: 61 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64  at if the second
bdc0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65   argument to xRe
bdd0: 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a  alloc is zero,.*
bde0: 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20  * xRealloc must 
bdf0: 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20  be a no-op - it 
be00: 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d  must not perform
be10: 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20   any allocation 
be20: 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69  or.** deallocati
be30: 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67 75 61  on.  ^SQLite gua
be40: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
be50: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
be60: 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
be70: 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
be80: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
be90: 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
bea0: 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73  oundup..** And s
beb0: 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65  o in cases where
bec0: 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73   xRoundup always
bed0: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74   returns a posit
bee0: 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78  ive number,.** x
bef0: 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66  Realloc can perf
bf00: 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74  orm exactly as t
bf10: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
bf20: 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  ary realloc() an
bf30: 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e  d.** still be in
bf40: 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68   compliance with
bf50: 20 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74   this specificat
bf60: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  ion..**.** xSize
bf70: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
bf80: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
bf90: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
bfa0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
bfb0: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
bfc0: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
bfd0: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
bfe0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
bff0: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
c000: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
c010: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
c020: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
c030: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
c040: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
c050: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
c060: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
c070: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
c080: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c090: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
c0a0: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
c0b0: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
c0c0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
c0d0: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
c0e0: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
c0f0: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
c100: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
c110: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
c120: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
c130: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
c140: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
c150: 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
c160: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c170: 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
c180: 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
c190: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
c1a0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
c1b0: 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
c1c0: 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
c1d0: 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
c1e0: 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
c1f0: 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
c200: 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
c210: 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
c220: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
c230: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
c240: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
c250: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
c260: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
c270: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
c280: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
c290: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
c2a0: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
c2b0: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
c2c0: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
c2d0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
c2e0: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
c2f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
c300: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
c310: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
c320: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
c330: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
c340: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
c350: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
c360: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
c370: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
c380: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
c390: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
c3a0: 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
c3b0: 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
c3c0: 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
c3d0: 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
c3e0: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
c3f0: 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
c400: 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
c410: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
c420: 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
c430: 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
c440: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
c450: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
c460: 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
c470: 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
c480: 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
c490: 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
c4a0: 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
c4b0: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
c4c0: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
c4d0: 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
c4e0: 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
c4f0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
c500: 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
c510: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
c520: 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
c530: 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
c540: 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
c550: 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
c560: 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
c570: 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
c580: 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
c590: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
c5a0: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
c5b0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
c5c0: 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
c5d0: 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
c5e0: 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
c5f0: 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
c600: 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
c610: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
c620: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
c630: 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
c640: 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
c650: 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
c660: 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
c670: 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
c680: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c690: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
c6a0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
c6b0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
c6c0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
c6d0: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
c6e0: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
c6f0: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
c700: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
c710: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
c720: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
c730: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
c740: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
c750: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
c760: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
c770: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
c780: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
c790: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
c7a0: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
c7b0: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
c7c0: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
c7d0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
c7e0: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
c7f0: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
c800: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
c810: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
c820: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
c830: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
c840: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
c850: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
c860: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
c870: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
c880: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
c890: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
c8a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
c8b0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
c8c0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
c8d0: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
c8e0: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
c8f0: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
c900: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c910: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
c920: 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
c930: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
c940: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
c950: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
c960: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
c970: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
c980: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
c990: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
c9a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
c9b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
c9c0: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
c9d0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
c9e0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
c9f0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
ca00: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
ca10: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
ca20: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
ca30: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
ca40: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
ca50: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
ca60: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
ca70: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
ca80: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
ca90: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
caa0: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
cab0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
cac0: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
cad0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
cae0: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
caf0: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
cb00: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
cb10: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
cb20: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
cb30: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
cb40: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
cb50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
cb60: 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
cb70: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
cb80: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
cb90: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
cba0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
cbb0: 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
cbc0: 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
cbd0: 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
cbe0: 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
cbf0: 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
cc00: 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
cc10: 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
cc20: 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
cc30: 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
cc40: 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
cc50: 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
cc60: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
cc70: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
cc80: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
cc90: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
cca0: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
ccb0: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
ccc0: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
ccd0: 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
cce0: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
ccf0: 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
cd00: 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
cd10: 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
cd20: 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
cd30: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
cd40: 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
cd50: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
cd60: 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
cd70: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
cd80: 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
cd90: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
cda0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
cdb0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
cdc0: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
cdd0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
cde0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
cdf0: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
ce00: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
ce10: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
ce20: 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
ce30: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
ce40: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
ce50: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
ce60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ce70: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
ce80: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
ce90: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
cea0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
ceb0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
cec0: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
ced0: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
cee0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
cef0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
cf00: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
cf10: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
cf20: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
cf30: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
cf40: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
cf50: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
cf60: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
cf70: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
cf80: 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
cf90: 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
cfa0: 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
cfb0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
cfc0: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
cfd0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
cfe0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
cff0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
d000: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
d010: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
d020: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
d030: 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
d040: 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
d050: 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
d060: 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
d070: 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
d080: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
d090: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
d0a0: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
d0b0: 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
d0c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
d0d0: 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
d0e0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
d0f0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d100: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
d110: 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
d120: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
d130: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
d140: 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
d150: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
d160: 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
d170: 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
d180: 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
d190: 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
d1a0: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
d1b0: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
d1c0: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
d1d0: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
d1e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d1f0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
d200: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
d210: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
d220: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
d230: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
d240: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
d250: 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
d260: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
d270: 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
d280: 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
d290: 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
d2a0: 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
d2b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
d2c0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
d2d0: 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
d2e0: 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
d2f0: 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
d300: 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
d310: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d320: 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
d330: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
d340: 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
d350: 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
d360: 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
d370: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
d380: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
d390: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
d3a0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
d3b0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
d3c0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
d3d0: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
d3e0: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
d3f0: 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
d400: 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
d410: 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
d420: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
d430: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
d440: 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
d450: 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
d460: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
d470: 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
d480: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
d490: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d4a0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
d4b0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
d4c0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d4d0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
d4e0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
d4f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
d500: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d510: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
d520: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
d530: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
d540: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
d550: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
d560: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
d570: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
d580: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
d590: 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
d5a0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
d5b0: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
d5c0: 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
d5d0: 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
d5e0: 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
d5f0: 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
d600: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
d610: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
d620: 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
d630: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
d640: 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
d650: 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
d660: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d670: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
d680: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
d690: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
d6a0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
d6b0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
d6c0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
d6d0: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
d6e0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d6f0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
d700: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
d710: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
d720: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
d730: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
d740: 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
d750: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
d760: 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
d770: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
d780: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
d790: 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
d7a0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
d7b0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
d7c0: 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
d7d0: 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
d7e0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
d7f0: 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
d800: 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
d810: 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
d820: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
d830: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
d840: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
d850: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
d860: 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
d870: 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20  nt of type int, 
d880: 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
d890: 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68   .** boolean, wh
d8a0: 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
d8b0: 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
d8c0: 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
d8d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20   allocation .** 
d8e0: 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
d8f0: 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
d900: 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
d910: 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68  are disabled, th
d920: 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  e .** following 
d930: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
d940: 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
d950: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
d960: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
d970: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
d980: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
d990: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
d9a0: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
d9b0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
d9c0: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
d9d0: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
d9e0: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
d9f0: 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
da00: 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
da10: 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
da20: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
da30: 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
da40: 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
da50: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
da60: 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
da70: 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
da80: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
da90: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
daa0: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
dab0: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
dac0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
dad0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
dae0: 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
daf0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
db00: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
db10: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
db20: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
db30: 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63  se for.** scratc
db40: 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65  h memory.  There
db50: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
db60: 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72  ents:  A pointer
db70: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
db80: 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
db90: 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
dba0: 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 61  he scrach alloca
dbb0: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
dbc0: 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
dbd0: 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
dbe0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
dbf0: 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
dc00: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
dc10: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
dc20: 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
dc30: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
dc40: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
dc50: 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72  f 16. The sz par
dc60: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
dc70: 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20   a few bytes.** 
dc80: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
dc90: 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73  actual scratch s
dca0: 70 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75  pace required du
dcb0: 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 6f 76  e to internal ov
dcc0: 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66  erhead..** The f
dcd0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
dce0: 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
dcf0: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
dd00: 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
dd10: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
dd20: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
dd30: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
dd40: 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
dd50: 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75  n one scratch bu
dd60: 66 66 65 72 20 70 65 72 20 74 68 72 65 61 64 2e  ffer per thread.
dd70: 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64    So.** N should
dd80: 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65   be set to the e
dd90: 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
dda0: 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
ddb0: 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
ddc0: 0a 2a 2a 20 6e 65 76 65 72 20 72 65 71 75 69 72  .** never requir
ddd0: 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  e a scratch buff
dde0: 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
ddf0: 74 68 61 6e 20 36 20 74 69 6d 65 73 20 74 68 65  than 6 times the
de00: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67   database.** pag
de10: 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69  e size. ^If SQLi
de20: 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
de30: 64 64 69 74 69 6f 6e 61 6c 20 73 63 72 61 74 63  dditional scratc
de40: 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
de50: 0a 2a 2a 20 77 68 61 74 20 69 73 20 70 72 6f 76  .** what is prov
de60: 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
de70: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
de80: 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
de90: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
dea0: 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
deb0: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
dec0: 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
ded0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
dee0: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
def0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
df00: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
df10: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
df20: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
df30: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
df40: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
df50: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
df60: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
df70: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
df80: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
df90: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
dfa0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
dfb0: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
dfc0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
dfd0: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
dfe0: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
dff0: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
e000: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
e010: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
e020: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
e030: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
e040: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
e050: 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
e060: 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
e070: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
e080: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
e090: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
e0a0: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
e0b0: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
e0c0: 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
e0d0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
e0e0: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
e0f0: 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
e100: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
e110: 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
e120: 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
e130: 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
e140: 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
e150: 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
e160: 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
e170: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
e180: 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
e190: 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
e1a0: 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
e1b0: 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
e1c0: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
e1d0: 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
e1e0: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
e1f0: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
e200: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
e210: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
e220: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
e230: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
e240: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
e250: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
e260: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
e270: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
e280: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
e290: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
e2a0: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
e2b0: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
e2c0: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
e2d0: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
e2e0: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
e2f0: 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
e300: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
e310: 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
e320: 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
e330: 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
e340: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
e350: 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
e360: 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
e370: 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  * ^The implement
e380: 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20  ation might use 
e390: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
e3a0: 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20  he N buffers to 
e3b0: 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20  hold .** memory 
e3c0: 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72  accounting infor
e3d0: 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f 69 6e  mation. The poin
e3e0: 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
e3f0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
e400: 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
e410: 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
e420: 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
e430: 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
e440: 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
e450: 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
e460: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e470: 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
e480: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
e490: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
e4a0: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
e4b0: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
e4c0: 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
e4d0: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
e4e0: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
e4f0: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
e500: 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
e510: 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
e520: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
e530: 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
e540: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
e550: 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
e560: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
e570: 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  s: An 8-byte ali
e580: 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
e590: 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
e5a0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
e5b0: 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
e5c0: 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
e5d0: 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
e5e0: 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
e5f0: 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
e600: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
e610: 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
e620: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
e630: 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
e640: 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
e650: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
e660: 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
e670: 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
e680: 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
e690: 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
e6a0: 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
e6b0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
e6c0: 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
e6d0: 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
e6e0: 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
e6f0: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
e700: 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
e710: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
e720: 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
e730: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
e740: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
e750: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
e760: 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
e770: 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
e780: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
e790: 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
e7a0: 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
e7b0: 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
e7c0: 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
e7d0: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
e7e0: 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
e7f0: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
e800: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
e810: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
e820: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e830: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
e840: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
e850: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
e860: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
e870: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
e880: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
e890: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
e8a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
e8b0: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
e8c0: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
e8d0: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
e8e0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
e8f0: 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
e900: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
e910: 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
e920: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
e930: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
e940: 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
e950: 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
e960: 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20  e.** content of 
e970: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
e980: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
e990: 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
e9a0: 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
e9b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
e9c0: 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
e9d0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
e9e0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
e9f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
ea00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
ea10: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
ea20: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
ea30: 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
ea40: 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
ea50: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
ea60: 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
ea70: 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
ea80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ea90: 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
eaa0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
eab0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
eac0: 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
ead0: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
eae0: 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ].</dd>.**.** <d
eaf0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
eb00: 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
eb10: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
eb20: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
eb30: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
eb40: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
eb50: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
eb60: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
eb70: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
eb80: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
eb90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
eba0: 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
ebb0: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
ebc0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
ebd0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
ebe0: 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
ebf0: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
ec00: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
ec10: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
ec20: 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
ec30: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
ec40: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
ec50: 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
ec60: 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
ec70: 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
ec80: 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
ec90: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
eca0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
ecb0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
ecc0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
ecd0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
ece0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
ecf0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
ed00: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
ed10: 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
ed20: 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
ed30: 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
ed40: 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
ed50: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
ed60: 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
ed70: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
ed80: 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
ed90: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
eda0: 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
edb0: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
edc0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
edd0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
ede0: 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
edf0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
ee00: 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
ee10: 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
ee20: 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
ee30: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
ee40: 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
ee50: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
ee60: 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
ee70: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
ee80: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
ee90: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
eea0: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
eeb0: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
eec0: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
eed0: 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
eee0: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
eef0: 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
ef00: 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
ef10: 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
ef20: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
ef30: 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
ef40: 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
ef50: 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
ef60: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
ef70: 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
ef80: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
ef90: 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
efa0: 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
efb0: 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
efc0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
efd0: 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
efe0: 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
eff0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
f000: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f 64  CONFIG_PCACHE</d
f010: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
f020: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
f030: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
f040: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
f050: 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
f060: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
f070: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  hods] object.  T
f080: 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
f090: 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  fies the interfa
f0a0: 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f  ce.** to a custo
f0b0: 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
f0c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20  lementation.)^  
f0d0: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
f0e0: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
f0f0: 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69  bject and uses i
f100: 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  t for page cache
f110: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f120: 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ons.</dd>.**.** 
f130: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f140: 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e  G_GETPCACHE</dt>
f150: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
f160: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
f170: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
f180: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
f190: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
f1a0: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
f1b0: 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  ds] object.  SQL
f1c0: 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
f1d0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
f1e0: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
f1f0: 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
f200: 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
f210: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f220: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
f230: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
f240: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
f250: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
f260: 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
f270: 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
f280: 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
f290: 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
f2a0: 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
f2b0: 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
f2c0: 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
f2d0: 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
f2e0: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
f2f0: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
f300: 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
f310: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
f320: 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
f330: 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
f340: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
f350: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
f360: 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
f370: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
f380: 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
f390: 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
f3a0: 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
f3b0: 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
f3c0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
f3d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
f3e0: 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
f3f0: 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
f400: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
f410: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
f420: 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
f430: 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
f440: 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
f450: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
f460: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
f470: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
f480: 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
f490: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
f4a0: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
f4b0: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
f4c0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
f4d0: 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
f4e0: 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
f4f0: 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
f500: 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
f510: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
f520: 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
f530: 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
f540: 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
f550: 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
f560: 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
f570: 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
f580: 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
f590: 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
f5a0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
f5b0: 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
f5c0: 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
f5d0: 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
f5e0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
f5f0: 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
f600: 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
f610: 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
f620: 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
f630: 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
f640: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
f650: 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
f660: 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
f670: 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
f680: 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
f690: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f6a0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
f6b0: 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
f6c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f6d0: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
f6e0: 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
f6f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f700: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
f710: 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
f720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f730: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
f740: 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
f750: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
f760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f770: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
f780: 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
f790: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
f7a0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
f7b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
f7c0: 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
f7d0: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
f7e0: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
f7f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
f800: 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
f810: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
f820: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
f830: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
f840: 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
f850: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
f860: 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
f870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f880: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
f890: 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
f8a0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
f8b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
f8c0: 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
f8d0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
f8e0: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
f8f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
f900: 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
f910: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
f920: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
f930: 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
f940: 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
f950: 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
f960: 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
f970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f980: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
f990: 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
f9a0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
f9b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
f9c0: 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73  E       14  /* s
f9d0: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
f9e0: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
f9f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
fa00: 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
fa10: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
fa20: 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
fa30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
fa40: 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
fa50: 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
fa60: 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  void* */../*.** 
fa70: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
fa80: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
fa90: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
faa0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
fab0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
fac0: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
fad0: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
fae0: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
faf0: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
fb00: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
fb10: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
fb20: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
fb30: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
fb40: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
fb50: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
fb60: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
fb70: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
fb80: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
fb90: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
fba0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
fbb0: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
fbc0: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
fbd0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
fbe0: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
fbf0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
fc00: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
fc10: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
fc20: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
fc30: 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
fc40: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
fc50: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
fc60: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
fc70: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
fc80: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
fc90: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
fca0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fcb0: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
fcc0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
fcd0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
fce0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
fcf0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
fd00: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
fd10: 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
fd20: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
fd30: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
fd40: 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
fd50: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
fd60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
fd70: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
fd80: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
fd90: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
fda0: 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
fdb0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
fdc0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
fdd0: 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
fde0: 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75   to an memory bu
fdf0: 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
fe00: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
fe10: 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
fe20: 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
fe30: 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
fe40: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
fe50: 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
fe60: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
fe70: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
fe80: 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
fe90: 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
fea0: 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
feb0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
fec0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
fed0: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
fee0: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
fef0: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
ff00: 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
ff10: 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
ff20: 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
ff30: 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
ff40: 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
ff50: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
ff60: 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
ff70: 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
ff80: 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
ff90: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
ffa0: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
ffb0: 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
ffc0: 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
ffd0: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
ffe0: 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
fff0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
10000 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
10010 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10020 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
10030 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
10040 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
10050 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
10060 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20  next smaller.** 
10070 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
10080 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
10090 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
100a0 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  DE]</dd>.**.** <
100b0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
100c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
100d0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30  LOOKASIDE    100
100e0 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
100f0 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  int */.../*.** C
10100 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
10110 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
10120 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
10130 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
10140 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
10150 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
10160 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
10170 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
10180 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
10190 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
101a0 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
101b0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
101c0 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
101d0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
101e0 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
101f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
10200 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
10210 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
10220 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
10230 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
10240 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
10250 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
10260 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
10270 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
10280 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
10290 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
102a0 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
102b0 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
102c0 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
102d0 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
102e0 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
102f0 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
10300 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
10310 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
10320 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
10330 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
10340 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
10350 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
10360 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
10370 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
10380 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
10390 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
103a0 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
103b0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
103c0 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
103d0 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
103e0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
103f0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
10400 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  id] of the most 
10410 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
10420 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
10430 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
10440 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61  from the [databa
10450 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
10460 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
10470 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f  rgument.  ^If no
10480 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
10490 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
104a0 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
104b0 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
104c0 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
104d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
104e0 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
104f0 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
10500 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20  a trigger, then 
10510 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
10520 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
10530 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ow is returned b
10540 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  y this routine a
10550 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
10560 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67  igger is running
10570 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
10580 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e  e trigger termin
10590 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ates, the value 
105a0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
105b0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65   routine.** reve
105c0 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20  rts to the last 
105d0 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62  value inserted b
105e0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
105f0 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  r fired.)^.**.**
10600 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
10610 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
10620 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
10630 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
10640 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
10650 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
10660 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
10670 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
10680 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
10690 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
106a0 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
106b0 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
106c0 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
106d0 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
106e0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
106f0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
10700 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
10710 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
10720 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
10730 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
10740 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
10750 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
10760 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
10770 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
10780 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
10790 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
107a0 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
107b0 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
107c0 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
107d0 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
107e0 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
107f0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
10800 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
10810 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
10820 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
10830 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
10840 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
10850 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
10860 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
10870 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
10880 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
10890 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
108a0 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
108b0 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
108c0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
108d0 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
108e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
108f0 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
10900 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
10910 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
10920 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
10930 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
10940 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
10950 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
10960 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10970 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
10980 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
10990 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
109a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
109b0 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
109c0 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
109d0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
109e0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
109f0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
10a00 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
10a10 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
10a20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
10a30 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
10a40 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
10a50 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
10a60 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
10a70 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
10a80 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
10a90 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
10aa0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
10ab0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
10ac0 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
10ad0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
10ae0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
10af0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
10b00 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
10b10 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
10b20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
10b30 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
10b40 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
10b50 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
10b60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
10b70 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
10b80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
10b90 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
10ba0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
10bb0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
10bc0 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
10bd0 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
10be0 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
10bf0 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
10c00 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
10c10 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
10c20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
10c30 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
10c40 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
10c50 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
10c60 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
10c70 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
10c80 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
10c90 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
10ca0 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
10cb0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
10cc0 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
10cd0 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
10ce0 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
10cf0 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
10d00 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
10d10 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
10d20 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
10d30 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
10d40 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
10d50 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
10d60 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
10d70 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
10d80 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
10d90 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
10da0 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
10db0 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
10dc0 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
10dd0 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
10de0 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
10df0 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
10e00 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
10e10 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
10e20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
10e30 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
10e40 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
10e50 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
10e60 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
10e70 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
10e80 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
10e90 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
10ea0 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
10eb0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
10ec0 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
10ed0 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
10ee0 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
10ef0 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
10f00 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
10f10 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
10f20 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
10f30 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
10f40 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
10f50 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
10f60 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
10f70 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
10f80 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
10f90 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
10fa0 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
10fb0 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
10fc0 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
10fd0 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
10fe0 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
10ff0 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
11000 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
11010 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
11020 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
11030 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
11040 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
11050 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
11060 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
11070 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
11080 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
11090 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
110a0 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
110b0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
110c0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
110d0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
110e0 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
110f0 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
11100 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
11110 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
11120 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
11130 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
11140 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
11150 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
11160 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
11170 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
11180 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
11190 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
111a0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
111b0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
111c0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
111d0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
111e0 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
111f0 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
11200 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
11210 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
11220 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
11230 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
11240 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
11250 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
11260 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
11270 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
11280 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
11290 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
112a0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
112b0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
112c0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
112d0 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
112e0 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
112f0 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
11300 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
11310 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
11320 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
11330 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
11340 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
11350 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
11360 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
11370 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
11380 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
11390 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
113a0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
113b0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
113c0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
113d0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
113e0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
113f0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
11400 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
11410 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11420 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
11430 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
11440 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
11450 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
11460 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
11470 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
11480 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
11490 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
114a0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
114b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
114c0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
114d0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
114e0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
114f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
11500 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
11510 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
11520 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
11530 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
11540 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
11550 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
11560 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
11570 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
11580 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
11590 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
115a0 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
115b0 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
115c0 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
115d0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
115e0 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
115f0 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
11600 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
11610 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
11620 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
11630 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
11640 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
11650 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
11660 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
11670 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
11680 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
11690 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
116a0 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
116b0 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
116c0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
116d0 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
116e0 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
116f0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
11700 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
11710 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
11720 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
11730 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
11740 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
11750 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
11760 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
11770 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
11780 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
11790 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
117a0 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
117b0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
117c0 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
117d0 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
117e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
117f0 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
11800 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
11810 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
11820 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
11830 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
11840 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
11850 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
11860 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
11870 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
11880 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
11890 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
118a0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
118b0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
118c0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
118d0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
118e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
118f0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
11900 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
11910 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
11920 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
11930 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
11940 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
11950 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
11960 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
11970 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
11980 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
11990 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
119a0 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
119b0 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
119c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
119d0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
119e0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
119f0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
11a00 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
11a10 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
11a20 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
11a30 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
11a40 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
11a50 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
11a60 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
11a70 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
11a80 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
11a90 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
11aa0 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
11ab0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
11ac0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
11ad0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
11ae0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
11af0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
11b00 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
11b10 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
11b20 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
11b30 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
11b40 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
11b50 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
11b60 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
11b70 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
11b80 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
11b90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11ba0 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
11bb0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
11bc0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
11bd0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
11be0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
11bf0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
11c00 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
11c10 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
11c20 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
11c30 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
11c40 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
11c50 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
11c60 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
11c70 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
11c80 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
11c90 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
11ca0 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
11cb0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
11cc0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
11cd0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
11ce0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
11cf0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
11d00 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
11d10 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
11d20 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
11d30 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
11d40 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
11d50 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
11d60 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
11d70 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
11d80 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
11d90 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
11da0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
11db0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
11dc0 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
11dd0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
11de0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
11df0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
11e00 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
11e10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
11e20 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
11e30 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
11e40 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
11e50 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
11e60 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
11e70 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
11e80 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
11e90 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
11ea0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
11eb0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
11ec0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
11ed0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
11ee0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
11ef0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
11f00 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
11f10 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
11f20 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
11f30 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
11f40 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
11f50 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
11f60 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
11f70 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
11f80 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
11f90 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
11fa0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
11fb0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
11fc0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
11fd0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
11fe0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
11ff0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
12000 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
12010 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
12020 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
12030 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
12040 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
12050 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
12060 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
12070 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
12080 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
12090 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
120a0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
120b0 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
120c0 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
120d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
120e0 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
120f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12100 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
12110 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
12120 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
12130 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
12140 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
12150 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
12160 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
12170 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
12180 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
12190 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
121a0 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
121b0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
121c0 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
121d0 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
121e0 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
121f0 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
12200 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
12210 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
12220 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
12230 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
12240 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
12250 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
12260 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
12270 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
12280 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
12290 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
122a0 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
122b0 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
122c0 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
122d0 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
122e0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
122f0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
12300 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
12310 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
12320 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
12330 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
12340 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
12350 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
12360 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
12370 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
12380 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
12390 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
123a0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
123b0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
123c0 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
123d0 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
123e0 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
123f0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
12400 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
12410 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
12420 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
12430 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
12440 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
12450 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
12460 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
12470 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
12480 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
12490 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
124a0 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
124b0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
124c0 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
124d0 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
124e0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
124f0 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
12500 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
12510 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
12520 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
12530 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
12540 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
12550 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12560 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
12570 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
12580 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
12590 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
125a0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
125b0 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
125c0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
125d0 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
125e0 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
125f0 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
12600 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
12610 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
12620 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
12630 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
12640 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
12650 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
12660 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
12670 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
12680 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
12690 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
126a0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
126b0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
126c0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
126d0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
126e0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
126f0 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
12700 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
12710 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
12720 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
12730 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
12740 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
12750 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
12760 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
12770 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
12780 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
12790 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
127a0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
127b0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
127c0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
127d0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
127e0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
127f0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
12800 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
12810 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
12820 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
12830 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
12840 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
12850 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
12860 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
12870 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  locked..**.** ^I
12880 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
12890 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
128a0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
128b0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
128c0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
128d0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
128e0 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
128f0 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
12900 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
12910 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
12920 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
12930 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
12940 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
12950 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
12960 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
12970 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
12980 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
12990 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
129a0 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
129b0 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
129c0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
129d0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
129e0 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
129f0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
12a00 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
12a10 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
12a20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
12a30 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
12a40 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
12a50 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
12a60 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
12a70 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
12a80 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
12a90 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
12aa0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
12ab0 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
12ac0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
12ad0 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
12ae0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
12af0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
12b00 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
12b10 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
12b20 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
12b30 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
12b40 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
12b50 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
12b60 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
12b70 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
12b80 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
12b90 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
12ba0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
12bb0 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
12bc0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
12bd0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
12be0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
12bf0 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
12c00 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
12c10 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
12c20 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
12c30 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
12c40 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
12c50 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
12c60 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
12c70 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
12c80 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
12c90 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
12ca0 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
12cb0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
12cc0 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
12cd0 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
12ce0 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
12cf0 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
12d00 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
12d10 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
12d20 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
12d30 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
12d40 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
12d50 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
12d60 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
12d70 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
12d80 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
12d90 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
12da0 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
12db0 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
12dc0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
12dd0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
12de0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
12df0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
12e00 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
12e10 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
12e20 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
12e30 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
12e40 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
12e50 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
12e60 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
12e70 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
12e80 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
12e90 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
12ea0 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
12eb0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
12ec0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
12ed0 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
12ee0 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
12ef0 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
12f00 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
12f10 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
12f20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
12f30 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
12f40 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
12f50 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
12f60 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
12f70 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
12f80 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
12f90 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
12fa0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
12fb0 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
12fc0 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
12fd0 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
12fe0 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
12ff0 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
13000 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
13010 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
13020 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
13030 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
13040 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
13050 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
13060 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
13070 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
13080 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
13090 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
130a0 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
130b0 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
130c0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
130d0 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
130e0 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
130f0 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49  .** readers.  ^I
13100 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
13110 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
13120 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
13130 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
13140 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
13150 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
13160 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
13170 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
13180 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
13190 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
131a0 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
131b0 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
131c0 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
131d0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
131e0 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63  .  ^This error c
131f0 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
13200 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
13210 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
13220 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
13230 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
13240 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
13250 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
13260 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
13270 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
13280 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
13290 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
132a0 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
132b0 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
132c0 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
132d0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
132e0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
132f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
13300 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
13310 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
13320 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
13330 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
13340 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
13350 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
13360 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
13370 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
13380 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
13390 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c  imeout()].** wil
133a0 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
133b0 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e  ear the busy han
133c0 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
133d0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
133e0 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
133f0 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
13400 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
13410 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13420 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
13430 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
13440 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
13450 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
13460 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
13470 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
13480 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
13490 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
134a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
134b0 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
134c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
134d0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
134e0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
134f0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
13500 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
13510 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
13520 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
13530 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
13540 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
13550 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
13560 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
13570 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
13580 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
13590 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
135a0 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
135b0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
135c0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
135d0 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
135e0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
135f0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
13600 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
13610 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
13620 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
13630 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
13640 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
13650 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
13660 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
13670 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
13680 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
13690 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
136a0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
136b0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
136c0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
136d0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
136e0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
136f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
13700 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
13710 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
13720 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
13730 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
13740 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
13750 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
13760 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
13770 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
13780 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
13790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
137a0 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
137b0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
137c0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
137d0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
137e0 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
137f0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
13800 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
13810 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
13820 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
13830 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
13840 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e  cleared.)^.*/.in
13850 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
13860 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
13870 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
13880 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
13890 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
138a0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
138b0 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ies.**.** Defini
138c0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
138d0 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
138e0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
138f0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
13900 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
13910 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
13920 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
13930 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
13940 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
13950 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
13960 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
13970 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
13980 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
13990 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
139a0 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
139b0 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
139c0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
139d0 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
139e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
139f0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
13a00 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
13a10 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
13a20 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
13a30 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
13a40 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
13a50 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
13a60 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
13a70 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
13a80 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
13a90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
13aa0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
13ab0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
13ac0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
13ad0 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
13ae0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
13af0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
13b00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
13b10 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
13b20 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
13b30 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
13b40 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
13b50 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
13b60 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
13b70 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
13b80 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
13b90 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
13ba0 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
13bb0 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
13bc0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
13bd0 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
13be0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
13bf0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
13c00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
13c10 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
13c20 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
13c30 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
13c40 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
13c50 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
13c60 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
13c70 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
13c80 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
13c90 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
13ca0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
13cb0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
13cc0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
13cd0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
13ce0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e  ()]..**.** As an
13cf0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
13d00 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
13d10 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
13d20 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
13d30 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
13d40 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
13d50 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
13d60 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
13d70 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
13d80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
13d90 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
13da0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
13db0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
13dc0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
13dd0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
13de0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
13df0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
13e00 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
13e10 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
13e20 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
13e30 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
13e40 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
13e50 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
13e60 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
13e70 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
13e80 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
13e90 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
13ea0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
13eb0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
13ec0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
13ed0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
13ee0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
13ef0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
13f00 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
13f10 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
13f20 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
13f30 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
13f40 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
13f50 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
13f60 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
13f70 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
13f80 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
13f90 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
13fa0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
13fb0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
13fc0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
13fd0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
13fe0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
13ff0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
14000 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
14010 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
14020 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
14030 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
14040 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
14050 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
14060 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
14070 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
14080 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
14090 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
140a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
140b0 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
140c0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
140d0 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
140e0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
140f0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
14100 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
14110 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
14120 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
14130 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
14140 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 73  table(),.** it s
14150 68 6f 75 6c 64 20 70 61 73 73 20 74 68 65 20 72  hould pass the r
14160 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
14170 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
14180 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
14190 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
141a0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
141b0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
141c0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
141d0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
141e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
141f0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
14200 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14210 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
14220 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
14230 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
14240 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
14250 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
14260 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
14270 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
14280 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
14290 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
142a0 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
142b0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
142c0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
142d0 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
142e0 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
142f0 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
14300 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
14310 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
14320 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
14330 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
14340 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
14350 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
14360 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
14370 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
14380 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
14390 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
143a0 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
143b0 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
143c0 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
143d0 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
143e0 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
143f0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
14400 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
14410 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
14420 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
14430 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
14440 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
14450 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
14460 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a  3_errmsg()].)^.*
14470 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
14480 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
14490 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
144a0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
144b0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
144c0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
144d0 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
144e0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
144f0 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
14500 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
14510 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
14520 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
14530 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
14540 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
14550 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
14560 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
14570 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
14580 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
14590 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
145a0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
145b0 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
145c0 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
145d0 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
145e0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
145f0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
14600 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14610 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
14620 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
14630 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
14640 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
14650 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
14660 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
14670 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
14680 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
14690 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
146a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
146b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
146c0 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
146d0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
146e0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
146f0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
14700 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
14710 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14720 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
14730 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
14740 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
14750 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
14760 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
14770 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
14780 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
14790 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
147a0 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
147b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
147c0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
147d0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
147e0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
147f0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
14800 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69  .**.** ^(In sqli
14810 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
14820 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
14830 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
14840 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
14850 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
14860 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
14870 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
14880 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
14890 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
148a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
148b0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
148c0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
148d0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
148e0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
148f0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
14900 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
14910 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
14920 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
14930 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
14940 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
14950 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
14960 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
14970 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
14980 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
14990 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
149a0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
149b0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
149c0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
149d0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
149e0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
149f0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
14a00 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
14a10 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
14a20 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
14a30 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
14a40 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
14a50 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
14a60 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
14a70 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
14a80 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
14a90 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
14aa0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
14ab0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
14ac0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
14ad0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
14ae0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
14af0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
14b00 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
14b10 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
14b20 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
14b30 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
14b40 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
14b50 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
14b60 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
14b70 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
14b80 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
14b90 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
14ba0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
14bb0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
14bc0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
14bd0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
14be0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
14bf0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
14c00 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
14c10 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
14c20 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
14c30 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
14c40 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
14c50 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
14c60 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
14c70 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
14c80 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
14c90 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
14ca0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
14cb0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
14cc0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
14cd0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
14ce0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
14cf0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
14d00 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
14d10 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
14d20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
14d30 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
14d40 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
14d50 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
14d60 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
14d70 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
14d80 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
14d90 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
14da0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
14db0 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
14dc0 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
14dd0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
14de0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
14df0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
14e00 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
14e10 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
14e20 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
14e30 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
14e40 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
14e50 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
14e60 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
14e70 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
14e80 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
14e90 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
14ea0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
14eb0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
14ec0 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
14ed0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
14ee0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14ef0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
14f00 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
14f10 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
14f20 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
14f30 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
14f40 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
14f50 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
14f60 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
14f70 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
14f80 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
14f90 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
14fa0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
14fb0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
14fc0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
14fd0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
14fe0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
14ff0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
15000 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
15010 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
15020 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
15030 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
15040 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
15050 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
15060 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
15070 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
15080 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
15090 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
150a0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
150b0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
150c0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
150d0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
150e0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
150f0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
15100 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
15110 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
15120 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
15130 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
15140 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
15150 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
15160 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
15170 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
15180 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
15190 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
151a0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
151b0 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
151c0 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
151d0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
151e0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
151f0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
15200 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
15210 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
15220 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
15230 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
15240 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
15250 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
15260 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
15270 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
15280 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
15290 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
152a0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
152b0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
152c0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
152d0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
152e0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
152f0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
15300 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
15310 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
15320 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
15330 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
15340 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
15350 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
15360 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
15370 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
15380 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
15390 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
153a0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
153b0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
153c0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
153d0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
153e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
153f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
15400 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
15410 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
15420 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
15430 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
15440 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
15450 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
15460 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
15470 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
15480 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
15490 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
154a0 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
154b0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
154c0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
154d0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
154e0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
154f0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
15500 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
15510 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
15520 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
15530 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
15540 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
15550 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
15560 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
15570 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
15580 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
15590 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
155a0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
155b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
155c0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
155d0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
155e0 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
155f0 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
15600 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
15610 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
15620 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
15630 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
15640 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15650 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
15660 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
15670 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
15680 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
15690 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
156a0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
156b0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
156c0 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
156d0 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
156e0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
156f0 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
15700 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
15710 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15720 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
15730 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
15740 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
15750 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
15760 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
15770 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
15780 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
15790 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
157a0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
157b0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
157c0 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
157d0 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
157e0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
157f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
15800 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
15810 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
15820 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
15830 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15840 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
15850 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
15860 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
15870 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
15880 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
15890 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
158a0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
158b0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
158c0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
158d0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
158e0 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
158f0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
15900 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
15910 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
15920 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
15930 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
15940 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
15950 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
15960 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
15970 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
15980 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
15990 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
159a0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
159b0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
159c0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
159d0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
159e0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
159f0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
15a00 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
15a10 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
15a20 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
15a30 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
15a40 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
15a50 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
15a60 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
15a70 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
15a80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
15a90 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
15aa0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
15ab0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
15ac0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
15ad0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
15ae0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
15af0 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
15b00 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
15b10 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
15b20 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
15b30 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
15b40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
15b50 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
15b60 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
15b70 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
15b80 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
15b90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15ba0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
15bb0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
15bc0 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
15bd0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15be0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
15bf0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
15c00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
15c10 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
15c20 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
15c30 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
15c40 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
15c50 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
15c60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
15c70 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
15c80 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
15c90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15ca0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
15cb0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
15cc0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
15cd0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
15ce0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
15cf0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
15d00 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
15d10 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
15d20 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15d30 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
15d40 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
15d50 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
15d60 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
15d70 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
15d80 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
15d90 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
15da0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
15db0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
15dc0 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
15dd0 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
15de0 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
15df0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
15e00 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
15e10 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
15e20 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
15e30 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
15e40 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
15e50 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
15e60 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
15e70 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
15e80 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
15e90 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
15ea0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15eb0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
15ec0 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
15ed0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
15ee0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
15ef0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
15f00 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
15f10 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
15f20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
15f30 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
15f40 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
15f50 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
15f60 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ary..**.** In SQ
15f70 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
15f80 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
15f90 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
15fa0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
15fb0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
15fc0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
15fd0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
15fe0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
15ff0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
16000 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
16010 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
16020 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
16030 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
16040 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
16050 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
16060 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
16070 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
16080 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
16090 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
160a0 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ls.** the system
160b0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
160c0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
160d0 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
160e0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
160f0 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
16100 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
16110 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
16120 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
16130 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
16140 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
16150 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
16160 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
16170 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
16180 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ors are detected
16190 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72  , but.** they ar
161a0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
161b0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
161c0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
161d0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
161e0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
161f0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
16200 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
16210 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
16220 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
16230 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
16240 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
16250 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
16260 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
16270 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
16280 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
16290 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
162a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
162b0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
162c0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
162d0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
162e0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
162f0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
16300 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
16310 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
16320 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
16330 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
16340 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
16350 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
16360 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
16370 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
16380 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
16390 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
163a0 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
163b0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
163c0 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
163d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
163e0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
163f0 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
16400 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
16410 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
16420 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
16430 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
16440 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
16450 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16460 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
16470 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
16480 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
16490 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
164a0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
164b0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
164c0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
164d0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
164e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
164f0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
16500 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
16510 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
16520 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
16530 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
16540 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
16550 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
16560 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
16570 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
16580 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
16590 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
165a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
165b0 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
165c0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
165d0 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
165e0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
165f0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
16600 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16610 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
16620 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
16630 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
16640 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
16650 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
16660 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
16670 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
16680 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
16690 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
166a0 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
166b0 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
166c0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
166d0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
166e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
166f0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
16700 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
16710 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
16720 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
16730 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
16740 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
16750 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
16760 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
16770 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
16780 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
16790 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
167a0 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
167b0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
167c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
167d0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
167e0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
167f0 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
16800 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
16810 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
16820 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
16830 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
16840 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
16850 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
16860 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
16870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
16880 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
16890 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
168a0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
168b0 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
168c0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
168d0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
168e0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
168f0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
16900 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
16910 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
16920 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
16930 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
16940 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
16950 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
16960 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
16970 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
16980 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
16990 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
169a0 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
169b0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
169c0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
169d0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
169e0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
169f0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
16a00 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
16a10 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
16a20 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
16a30 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
16a40 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
16a50 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
16a60 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
16a70 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
16a80 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
16a90 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
16aa0 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
16ab0 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
16ac0 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
16ad0 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
16ae0 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
16af0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
16b00 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
16b10 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
16b20 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e  ] object..** ^On
16b30 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
16b40 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
16b50 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
16b60 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
16b70 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
16b80 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
16b90 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
16ba0 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
16bb0 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
16bc0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
16bd0 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
16be0 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
16bf0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
16c00 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
16c10 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
16c20 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
16c30 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
16c40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16c50 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
16c60 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
16c70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
16c80 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
16c90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
16ca0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
16cb0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
16cc0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
16cd0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
16ce0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
16cf0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
16d00 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
16d10 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
16d20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
16d30 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
16d40 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
16d50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
16d60 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
16d70 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
16d80 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
16d90 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
16da0 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
16db0 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
16dc0 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
16dd0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
16de0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
16df0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
16e00 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
16e10 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
16e20 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
16e30 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
16e40 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
16e50 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
16e60 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
16e70 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
16e80 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
16e90 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
16ea0 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
16eb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
16ec0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
16ed0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
16ee0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
16ef0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
16f00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
16f10 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
16f20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
16f30 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
16f40 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
16f50 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
16f60 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
16f70 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
16f80 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
16f90 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
16fa0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
16fb0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
16fc0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
16fd0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
16fe0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
16ff0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
17000 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
17010 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
17020 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
17030 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
17040 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
17050 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
17060 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
17070 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
17080 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
17090 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
170a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
170b0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
170c0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
170d0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
170e0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
170f0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
17100 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
17110 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
17120 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
17130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
17140 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17150 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17160 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
17170 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
17180 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
17190 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
171a0 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
171b0 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
171c0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
171d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
171e0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
171f0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
17200 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
17210 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
17220 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
17230 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
17240 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
17250 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
17260 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
17270 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
17280 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
17290 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
172a0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
172b0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
172c0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
172d0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
172e0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
172f0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
17300 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
17310 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17320 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
17330 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
17340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
17350 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
17360 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
17370 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
17380 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
17390 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
173a0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
173b0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
173c0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
173d0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
173e0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
173f0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
17400 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
17410 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
17420 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
17430 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
17440 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
17450 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
17460 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
17470 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
17480 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
17490 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
174a0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
174b0 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
174c0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
174d0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
174e0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
174f0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
17500 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
17510 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
17520 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
17530 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
17540 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
17550 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
17560 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
17570 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
17580 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
17590 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
175a0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
175b0 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
175c0 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
175d0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
175e0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
175f0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
17600 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
17610 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
17620 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
17630 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
17640 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
17650 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
17660 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
17670 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
17680 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
17690 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
176a0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
176b0 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
176c0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
176d0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
176e0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
176f0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
17700 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
17710 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
17720 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
17730 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
17740 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
17750 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
17760 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
17770 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
17780 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
17790 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
177a0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
177b0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
177c0 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
177d0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
177e0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
177f0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
17800 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
17810 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
17820 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
17830 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
17840 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
17850 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
17860 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
17870 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
17880 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
17890 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
178a0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
178b0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
178c0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
178d0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
178e0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
178f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17900 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
17910 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
17920 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17930 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
17940 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
17950 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
17960 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17970 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
17980 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
17990 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
179a0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
179b0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
179c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
179d0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
179e0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
179f0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
17a00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17a10 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
17a20 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
17a30 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
17a40 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
17a50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17a60 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
17a70 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
17a80 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
17a90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
17aa0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
17ab0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
17ac0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
17ad0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
17ae0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17af0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
17b00 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
17b10 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
17b20 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
17b30 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
17b40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
17b50 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
17b60 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
17b70 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
17b80 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
17b90 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
17ba0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
17bb0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
17bc0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
17bd0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
17be0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
17bf0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
17c00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17c10 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
17c20 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
17c30 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
17c40 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
17c50 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
17c60 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
17c70 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
17c80 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
17c90 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
17ca0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
17cb0 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
17cc0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
17cd0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
17ce0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
17cf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17d00 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
17d10 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
17d20 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
17d30 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
17d40 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
17d50 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
17d60 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
17d70 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
17d80 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
17d90 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
17da0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
17db0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
17dc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
17dd0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
17de0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
17df0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
17e00 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
17e10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
17e20 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
17e30 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
17e40 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
17e50 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
17e60 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
17e70 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
17e80 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
17e90 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
17ea0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
17eb0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
17ec0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
17ed0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
17ee0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
17ef0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
17f00 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
17f10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17f20 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
17f30 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
17f40 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
17f50 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
17f60 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
17f70 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
17f80 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
17f90 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
17fa0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
17fb0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
17fc0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
17fd0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
17fe0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
17ff0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
18000 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
18010 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
18020 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
18030 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
18040 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
18050 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
18060 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
18070 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
18080 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
18090 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
180a0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
180b0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
180c0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
180d0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
180e0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
180f0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
18100 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
18110 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
18120 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
18130 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
18140 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
18150 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
18160 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
18170 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
18180 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
18190 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
181a0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
181b0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
181c0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
181d0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
181e0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
181f0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
18200 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
18210 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
18220 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
18230 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
18240 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
18250 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18260 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
18270 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
18280 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
18290 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
182a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
182b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
182c0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
182d0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
182e0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
182f0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
18300 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
18310 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
18320 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
18330 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
18340 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
18350 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
18360 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
18370 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18380 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18390 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
183a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
183b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
183c0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
183d0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
183e0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
183f0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
18400 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18410 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18420 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
18430 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18440 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18450 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18460 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18470 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
18480 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
18490 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
184a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
184b0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
184c0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
184d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
184e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
184f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18500 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
18510 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
18520 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
18530 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18540 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18550 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
18560 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
18570 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
18580 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18590 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
185a0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
185b0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
185c0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
185d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
185e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
185f0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
18600 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
18610 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
18620 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18640 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
18650 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
18660 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18670 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18690 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
186a0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
186b0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
186c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
186d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
186e0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
186f0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
18700 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
18710 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18730 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
18740 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
18750 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
18760 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18780 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
18790 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
187a0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
187b0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
187c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
187d0 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
187e0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
187f0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
18800 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18810 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
18820 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
18830 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
18840 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
18850 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18860 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
18870 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
18880 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
18890 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
188a0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
188b0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
188c0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
188d0 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
188e0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
188f0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18900 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
18910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
18920 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18930 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18940 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18950 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
18960 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
18970 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
18980 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
18990 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
189a0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
189b0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
189c0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
189d0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
189e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
189f0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
18a00 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
18a10 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
18a20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18a30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18a40 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
18a50 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
18a60 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
18a70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18a80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18a90 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
18aa0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
18ab0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18ac0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
18ad0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18ae0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
18af0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
18b00 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
18b10 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18b20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18b30 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
18b40 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
18b50 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
18b60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18b70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18b80 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
18b90 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
18ba0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
18bb0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18bc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18bd0 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
18be0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
18bf0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
18c00 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18c10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
18c20 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
18c30 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
18c40 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
18c50 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18c60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18c70 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
18c80 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
18c90 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
18ca0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
18cb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18cc0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
18cd0 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
18ce0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
18cf0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
18d00 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
18d10 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
18d20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
18d30 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
18d40 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
18d50 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
18d60 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
18d70 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
18d80 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
18d90 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
18da0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
18db0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18dc0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
18dd0 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
18de0 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
18df0 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
18e00 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
18e10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
18e20 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
18e30 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
18e40 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
18e50 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
18e60 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
18e70 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
18e80 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
18e90 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
18ea0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
18eb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
18ec0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
18ed0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
18ee0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
18ef0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
18f00 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
18f10 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
18f20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
18f30 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
18f40 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
18f50 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
18f60 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
18f70 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
18f80 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
18f90 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
18fa0 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
18fb0 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
18fc0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
18fd0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
18fe0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
18ff0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
19000 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
19010 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
19020 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
19030 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
19040 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
19050 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
19060 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
19070 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
19080 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
19090 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
190a0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
190b0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
190c0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
190d0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
190e0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
190f0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
19100 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
19110 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
19120 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
19130 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
19140 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
19150 20 74 6f 20 72 75 6e 2e 0a 2a 2f 0a 76 6f 69 64   to run..*/.void
19160 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
19170 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
19180 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
19190 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
191a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
191b0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
191c0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
191d0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
191e0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
191f0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
19200 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
19210 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
19220 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
19230 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
19240 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
19250 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61  ine configures a
19260 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19270 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67  on - the.** prog
19280 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20  ress callback - 
19290 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
192a0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
192b0 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e  ing long.** runn
192c0 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ing calls to [sq
192d0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
192e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
192f0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
19300 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41  get_table()].  A
19310 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
19320 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
19330 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
19340 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
19350 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
19360 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
19370 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
19380 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
19390 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
193a0 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
193b0 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
193c0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
193d0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
193e0 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
193f0 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
19400 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
19410 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
19420 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  ss handler must 
19430 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
19440 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
19450 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
19460 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
19470 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
19480 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
19490 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
194a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
194b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
194c0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
194d0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
194e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
194f0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
19500 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
19510 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
19520 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
19530 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19540 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
19550 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
19560 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
19570 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
19580 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
19590 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
195a0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
195b0 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
195c0 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
195d0 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67   whose name is g
195e0 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66  iven by the.** f
195f0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
19600 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
19610 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
19620 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
19630 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
19640 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
19650 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
19660 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
19670 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
19680 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
19690 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
196a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
196b0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
196c0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
196d0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
196e0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
196f0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
19700 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
19710 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
19720 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
19730 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
19740 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
19750 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
19760 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
19770 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
19780 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
19790 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
197a0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
197b0 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
197c0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
197d0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
197e0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
197f0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
19800 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
19810 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
19820 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
19830 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
19840 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
19850 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
19860 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
19870 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
19880 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
19890 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
198a0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
198b0 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
198c0 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
198d0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
198e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
198f0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
19900 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
19910 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
19920 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
19930 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
19940 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
19950 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
19960 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
19970 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
19980 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
19990 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
199a0 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
199b0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
199c0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
199d0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
199e0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
199f0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
19a00 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
19a10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
19a20 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
19a30 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
19a40 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
19a50 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
19a60 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
19a70 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
19a80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
19a90 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
19aa0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
19ab0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
19ac0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
19ad0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
19ae0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
19af0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
19b00 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
19b10 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
19b20 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
19b30 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
19b40 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
19b50 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
19b60 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
19b70 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
19b80 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
19b90 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
19ba0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
19bb0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
19bc0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
19bd0 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
19be0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
19bf0 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  HE],.** and/or [
19c00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
19c10 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a  ATECACHE] flags:
19c20 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
19c30 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
19c40 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
19c50 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
19c60 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
19c70 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
19c80 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
19c90 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
19ca0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
19cb0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
19cc0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
19cd0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
19ce0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
19cf0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
19d00 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
19d10 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
19d20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
19d30 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
19d40 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
19d50 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
19d60 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
19d70 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
19d80 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
19d90 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
19da0 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
19db0 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
19dc0 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
19dd0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
19de0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
19df0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
19e00 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
19e10 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
19e20 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
19e30 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
19e40 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
19e50 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
19e60 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74  ates it if.** it
19e70 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
19e80 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
19e90 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
19ea0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
19eb0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
19ec0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
19ed0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
19ee0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
19ef0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
19f00 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
19f10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
19f20 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
19f30 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
19f40 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
19f50 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
19f60 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
19f70 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
19f80 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
19f90 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
19fa0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
19fb0 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  MUTEX],.** [SQLI
19fc0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
19fd0 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  CHE] and/or [SQL
19fe0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
19ff0 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20  ACHE] flags,.** 
1a000 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1a010 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
1a020 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
1a030 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1a040 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
1a050 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1a060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1a070 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
1a080 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
1a090 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
1a0a0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
1a0b0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
1a0c0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
1a0d0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
1a0e0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1a0f0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
1a100 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1a110 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1a120 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1a130 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
1a140 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
1a150 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
1a160 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
1a170 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
1a180 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
1a190 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
1a1a0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1a1b0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
1a1c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1a1d0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
1a1e0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
1a1f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1a200 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
1a210 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
1a220 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
1a230 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1a240 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
1a250 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
1a260 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
1a270 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
1a280 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
1a290 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1a2a0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1a2b0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
1a2c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a2d0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
1a2e0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
1a2f0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1a300 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
1a310 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nabled..**.** ^I
1a320 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1a330 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
1a340 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1a350 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
1a360 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
1a370 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1a380 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
1a390 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1a3a0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1a3b0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1a3c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a3d0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1a3e0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1a3f0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1a400 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1a410 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1a420 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1a430 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1a440 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1a450 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1a460 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1a470 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1a480 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1a490 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1a4a0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1a4b0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1a4c0 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1a4d0 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1a4e0 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1a4f0 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1a500 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1a510 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
1a520 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
1a530 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1a540 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
1a550 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1a560 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
1a570 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
1a580 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
1a590 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
1a5a0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
1a5b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a5c0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1a5d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
1a5e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1a5f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a600 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
1a610 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1a620 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
1a630 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
1a640 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1a650 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
1a660 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1a670 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
1a680 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
1a690 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1a6a0 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
1a6b0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
1a6c0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1a6d0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
1a6e0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   used..**.** <b>
1a6f0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
1a700 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
1a710 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
1a720 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
1a730 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
1a740 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1a750 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a760 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
1a770 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
1a780 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
1a790 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
1a7a0 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
1a7b0 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
1a7c0 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
1a7d0 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
1a7e0 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
1a7f0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
1a800 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
1a810 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1a820 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1a830 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1a840 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
1a850 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
1a860 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1a870 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
1a880 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1a890 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1a8a0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1a8b0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
1a8c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
1a8d0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
1a8e0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1a8f0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1a900 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
1a910 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1a920 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1a930 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1a940 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1a950 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
1a960 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
1a970 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1a980 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
1a990 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1a9a0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
1a9b0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1a9c0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
1a9d0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
1a9e0 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
1a9f0 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
1aa00 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
1aa10 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
1aa20 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
1aa30 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
1aa40 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
1aa50 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
1aa60 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1aa70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1aa80 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
1aa90 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
1aaa0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1aab0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
1aac0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
1aad0 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
1aae0 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
1aaf0 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
1ab00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ab10 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
1ab20 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
1ab30 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
1ab40 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
1ab50 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
1ab60 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
1ab70 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
1ab80 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
1ab90 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1aba0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1abb0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
1abc0 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
1abd0 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
1abe0 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
1abf0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1ac00 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
1ac10 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
1ac20 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
1ac30 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
1ac40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
1ac50 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
1ac60 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
1ac70 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
1ac80 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
1ac90 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
1aca0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
1acb0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1acc0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1acd0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
1ace0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
1acf0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
1ad00 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
1ad10 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
1ad20 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
1ad30 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
1ad40 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
1ad50 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
1ad60 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
1ad70 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
1ad80 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
1ad90 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
1ada0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1adb0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
1adc0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
1add0 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ns.)^.**.** When
1ade0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1adf0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1ae00 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
1ae10 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
1ae20 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
1ae30 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
1ae40 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
1ae50 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
1ae60 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
1ae70 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
1ae80 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
1ae90 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
1aea0 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
1aeb0 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
1aec0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
1aed0 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
1aee0 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
1aef0 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
1af00 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1af10 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
1af20 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
1af30 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
1af40 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
1af50 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
1af60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
1af70 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
1af80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
1af90 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
1afa0 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
1afb0 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
1afc0 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
1afd0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
1afe0 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
1aff0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
1b000 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
1b010 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
1b020 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
1b030 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
1b040 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
1b050 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
1b060 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
1b070 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
1b080 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
1b090 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
1b0a0 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
1b0b0 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
1b0c0 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
1b0d0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
1b0e0 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
1b0f0 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
1b100 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
1b110 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
1b120 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
1b130 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
1b140 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
1b150 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1b160 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
1b170 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
1b180 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1b190 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1b1a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
1b1b0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
1b1c0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1b1d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1b1e0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
1b1f0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
1b200 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
1b210 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
1b220 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
1b230 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
1b240 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
1b250 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
1b260 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
1b270 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
1b280 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
1b290 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
1b2a0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
1b2b0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
1b2c0 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
1b2d0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
1b2e0 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
1b2f0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
1b300 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
1b310 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1b320 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b330 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
1b340 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
1b350 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
1b360 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
1b370 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
1b380 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
1b390 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
1b3a0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
1b3b0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
1b3c0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
1b3d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
1b3e0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
1b3f0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
1b400 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
1b410 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
1b420 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
1b430 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
1b440 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
1b450 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
1b460 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
1b470 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
1b480 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1b490 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
1b4a0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
1b4b0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
1b4c0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
1b4d0 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
1b4e0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1b4f0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
1b500 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1b510 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
1b520 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
1b530 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
1b540 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
1b550 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
1b560 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
1b570 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
1b580 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
1b590 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
1b5a0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
1b5b0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
1b5c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1b5d0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
1b5e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b5f0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
1b600 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
1b610 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
1b620 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
1b630 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
1b640 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
1b650 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
1b660 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
1b670 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
1b680 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
1b690 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
1b6a0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
1b6b0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
1b6c0 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74  ruct.  The funct
1b6d0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1b6e0 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a  old limit.)^.**.
1b6f0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
1b700 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
1b710 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
1b720 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
1b730 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68 65 20  d..** ^(For the 
1b740 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f  limit category o
1b750 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58  f SQLITE_LIMIT_X
1b760 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  YZ there is a .*
1b770 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
1b780 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
1b790 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c   set by a compil
1b7a0 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63  e-time C preproc
1b7b0 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65  essor macro name
1b7c0 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  d .** [limits | 
1b7d0 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e  SQLITE_MAX_XYZ].
1b7e0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
1b7f0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
1b800 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
1b810 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
1b820 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
1b830 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
1b840 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
1b850 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
1b860 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
1b870 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
1b880 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 52 75   bound..**.** Ru
1b890 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
1b8a0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
1b8b0 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
1b8c0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
1b8d0 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
1b8e0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1b8f0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
1b900 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
1b910 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
1b920 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
1b930 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
1b940 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
1b950 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
1b960 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
1b970 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
1b980 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
1b990 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
1b9a0 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
1b9b0 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
1b9c0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
1b9d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
1b9e0 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
1b9f0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
1ba00 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
1ba10 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
1ba20 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
1ba30 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
1ba40 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
1ba50 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
1ba60 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
1ba70 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
1ba80 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
1ba90 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
1baa0 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
1bab0 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
1bac0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
1bad0 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
1bae0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
1baf0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
1bb00 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
1bb10 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
1bb20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
1bb30 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
1bb40 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
1bb50 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
1bb60 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
1bb70 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
1bb80 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
1bb90 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1bba0 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
1bbb0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
1bbc0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
1bbd0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
1bbe0 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
1bbf0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
1bc00 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
1bc10 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
1bc20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1bc30 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
1bc40 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
1bc50 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
1bc60 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
1bc70 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
1bc80 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
1bc90 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
1bca0 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
1bcb0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1bcc0 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
1bcd0 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
1bce0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
1bcf0 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
1bd00 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
1bd10 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
1bd20 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
1bd30 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
1bd40 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
1bd50 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
1bd60 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
1bd70 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
1bd80 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53   <dl>.** ^(<dt>S
1bd90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1bda0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1bdb0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
1bdc0 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
1bdd0 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
1bde0 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  ow.<dd>)^.**.** 
1bdf0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1be00 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
1be10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1be20 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1be30 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1be40 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
1be50 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1be60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1be70 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
1be80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1be90 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1bea0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
1beb0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
1bec0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
1bed0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
1bee0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1bef0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
1bf00 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
1bf10 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
1bf20 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
1bf30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1bf40 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
1bf50 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
1bf60 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1bf70 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
1bf80 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
1bf90 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
1bfa0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1bfb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1bfc0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
1bfd0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1bfe0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
1bff0 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
1c000 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
1c010 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
1c020 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1c030 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
1c040 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c050 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
1c060 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
1c070 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
1c080 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
1c090 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
1c0a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c   SQL statement.<
1c0b0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1c0c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c0d0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
1c0e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c0f0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
1c100 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
1c110 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
1c120 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1c130 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1c140 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c150 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c160 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
1c170 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
1c180 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e  .)^</dd>.**.** ^
1c190 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1c1a0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1c1b0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1c1c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1c1d0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
1c1e0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
1c1f0 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
1c200 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
1c210 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
1c220 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1c230 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1c240 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
1c250 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1c260 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69  r of variables i
1c270 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1c280 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62  nt that can.** b
1c290 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29 5e 0a  e bound.</dd>)^.
1c2a0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1c2b0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
1c2c0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
1c2d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
1c2e0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
1c2f0 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
1c300 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
1c310 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c320 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
1c330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c340 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
1c350 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
1c360 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
1c370 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
1c380 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
1c390 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c3a0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
1c3b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
1c3c0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
1c3d0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
1c3e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
1c3f0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
1c400 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
1c410 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
1c420 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
1c430 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
1c440 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
1c450 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
1c460 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
1c470 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
1c480 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
1c490 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
1c4a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c4b0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
1c4c0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
1c4d0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c4e0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1c4f0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
1c500 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c510 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
1c520 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f             10../
1c530 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1c540 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
1c550 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
1c560 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
1c570 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
1c580 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
1c590 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
1c5a0 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
1c5b0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
1c5c0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
1c5d0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
1c5e0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1c5f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
1c600 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
1c610 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
1c620 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
1c630 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
1c640 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
1c650 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1c660 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1c670 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
1c680 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
1c690 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
1c6a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c6b0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
1c6c0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
1c6d0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
1c6e0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
1c6f0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
1c700 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
1c710 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
1c720 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
1c730 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
1c740 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
1c750 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1c760 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
1c770 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
1c780 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1c790 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
1c7a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1c7b0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
1c7c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1c7d0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
1c7e0 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
1c7f0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
1c800 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
1c810 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1c820 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
1c830 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1c840 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
1c850 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
1c860 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
1c870 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
1c880 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
1c890 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
1c8a0 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
1c8b0 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
1c8c0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
1c8d0 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
1c8e0 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
1c8f0 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
1c900 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
1c910 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
1c920 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
1c930 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
1c940 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
1c950 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
1c960 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
1c970 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
1c980 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
1c990 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
1c9a0 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
1c9b0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
1c9c0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
1c9d0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
1c9e0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
1c9f0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
1ca00 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
1ca10 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a  ator bytes..**.*
1ca20 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
1ca30 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
1ca40 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
1ca50 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
1ca60 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
1ca70 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
1ca80 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
1ca90 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
1caa0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
1cab0 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
1cac0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
1cad0 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
1cae0 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
1caf0 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
1cb00 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
1cb10 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
1cb20 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
1cb30 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
1cb40 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
1cb50 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
1cb60 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
1cb70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
1cb80 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
1cb90 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
1cba0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
1cbb0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
1cbc0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
1cbd0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
1cbe0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
1cbf0 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
1cc00 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
1cc10 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
1cc20 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
1cc30 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
1cc40 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
1cc50 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
1cc60 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
1cc70 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1cc80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1cc90 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
1cca0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
1ccb0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
1ccc0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
1ccd0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
1cce0 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
1ccf0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
1cd00 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
1cd10 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
1cd20 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
1cd30 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1cd40 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
1cd50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1cd60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
1cd70 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1cd80 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
1cd90 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
1cda0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
1cdb0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
1cdc0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
1cdd0 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
1cde0 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
1cdf0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1ce00 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
1ce10 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
1ce20 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
1ce30 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
1ce40 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
1ce50 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
1ce60 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
1ce70 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1ce80 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
1ce90 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
1cea0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
1ceb0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
1cec0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1ced0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
1cee0 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
1cef0 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
1cf00 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
1cf10 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
1cf20 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
1cf30 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
1cf40 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
1cf50 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1cf60 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
1cf70 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
1cf80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1cf90 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
1cfa0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
1cfb0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
1cfc0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
1cfd0 74 20 61 67 61 69 6e 2e 20 20 5e 49 66 20 74 68  t again.  ^If th
1cfe0 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
1cff0 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79  nged in.** a way
1d000 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
1d010 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
1d020 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
1d030 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1d040 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
1d050 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1d060 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
1d070 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1d080 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  r, [SQLITE_SCHEM
1d090 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66  A] is.** now a f
1d0a0 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c  atal error.  Cal
1d0b0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
1d0c0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69  epare_v2()] agai
1d0d0 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20  n will not make 
1d0e0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20  the.** error go 
1d0f0 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65  away.  Note: use
1d100 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d110 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ()] to find the 
1d120 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70  text.** of the p
1d130 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61  arsing error tha
1d140 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20  t results in an 
1d150 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1d160 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e  return..** </li>
1d170 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
1d180 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
1d190 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
1d1a0 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
1d1b0 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
1d1c0 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
1d1d0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
1d1e0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
1d1f0 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
1d200 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
1d210 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
1d220 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
1d230 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
1d240 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
1d250 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
1d260 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
1d270 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
1d280 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
1d290 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1d2a0 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
1d2b0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
1d2c0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
1d2d0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
1d2e0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
1d2f0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
1d300 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
1d310 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
1d320 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
1d330 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1d340 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
1d350 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
1d360 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 5b  the value of a [
1d370 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
1d380 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
1d390 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
1d3a0 6d 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67 65 20  might.** change 
1d3b0 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 20 66  the query plan f
1d3c0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  or a statement, 
1d3d0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
1d3e0 6e 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61 75 74  nt may be.** aut
1d3f0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1d400 70 69 6c 65 64 20 28 61 73 20 69 66 20 74 68 65  piled (as if the
1d410 72 65 20 68 61 64 20 62 65 65 6e 20 61 20 73 63  re had been a sc
1d420 68 65 6d 61 20 63 68 61 6e 67 65 29 20 6f 6e 20  hema change) on 
1d430 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 5b 73  the first .** [s
1d440 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
1d450 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
1d460 79 20 63 68 61 6e 67 65 20 74 6f 20 74 68 65 20  y change to the 
1d470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1d480 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
1d490 73 5d 20 6f 66 20 74 68 65 20 5b 70 61 72 61 6d  s] of the [param
1d4a0 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e  eter]. .** </li>
1d4b0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
1d4c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1d4d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1d4e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1d4f0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1d500 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1d510 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1d520 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1d530 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1d540 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1d550 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1d560 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1d570 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1d580 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1d590 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1d5a0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1d5b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1d5c0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1d5d0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1d5e0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1d5f0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1d600 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1d610 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
1d620 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1d630 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1d640 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1d650 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1d660 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1d670 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1d680 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1d690 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1d6a0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1d6b0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1d6c0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1d6d0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1d6e0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1d6f0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1d700 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1d710 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1d720 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1d730 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1d740 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1d750 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
1d760 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1d770 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1d780 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1d790 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1d7a0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1d7b0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1d7c0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1d7d0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1d7e0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1d7f0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1d800 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1d810 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1d820 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1d830 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1d840 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1d850 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1d860 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1d870 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1d880 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1d890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d8a0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
1d8b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1d8c0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1d8d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1d8e0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1d8f0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1d900 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1d910 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1d920 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1d930 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1d940 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1d950 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1d960 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1d970 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1d980 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1d990 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1d9a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1d9b0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1d9c0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1d9d0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1d9e0 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
1d9f0 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
1da00 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
1da10 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
1da20 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
1da30 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
1da40 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
1da50 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
1da60 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
1da70 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
1da80 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
1da90 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
1daa0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1dab0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1dac0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1dad0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1dae0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1daf0 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
1db00 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1db10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1db20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
1db30 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
1db40 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1db50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1db60 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
1db70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1db80 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
1db90 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
1dba0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
1dbb0 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
1dbc0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
1dbd0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
1dbe0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
1dbf0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
1dc00 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
1dc10 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
1dc20 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
1dc30 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
1dc40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1dc50 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
1dc60 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
1dc70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
1dc80 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
1dc90 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
1dca0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1dcb0 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
1dcc0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
1dcd0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
1dce0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
1dcf0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
1dd00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1dd10 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
1dd20 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
1dd30 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
1dd40 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
1dd50 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1dd60 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
1dd70 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
1dd80 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
1dd90 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
1dda0 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
1ddb0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
1ddc0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
1ddd0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1dde0 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
1ddf0 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
1de00 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
1de10 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
1de20 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
1de30 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
1de40 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
1de50 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
1de60 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1de70 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1de80 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
1de90 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
1dea0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1deb0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1dec0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
1ded0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
1dee0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
1def0 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
1df00 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
1df10 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
1df20 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
1df30 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
1df40 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
1df50 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
1df60 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
1df70 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
1df80 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
1df90 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
1dfa0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
1dfb0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
1dfc0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
1dfd0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
1dfe0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
1dff0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1e000 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
1e010 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
1e020 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
1e030 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
1e040 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
1e050 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
1e060 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1e070 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
1e080 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
1e090 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
1e0a0 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72  tween between pr
1e0b0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1e0c0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1e0d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1e0e0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
1e0f0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
1e100 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1e110 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e120 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
1e130 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
1e140 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
1e150 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1e160 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1e170 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1e180 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
1e190 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1e1a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
1e1b0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
1e1c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
1e1d0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
1e1e0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
1e1f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1e200 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
1e210 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
1e220 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
1e230 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
1e240 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1e250 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
1e260 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1e270 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
1e280 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
1e290 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
1e2a0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
1e2b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1e2c0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
1e2d0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1e2e0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
1e2f0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
1e300 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
1e310 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
1e320 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
1e330 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
1e340 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
1e350 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
1e360 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
1e370 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
1e380 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
1e390 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1e3a0 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
1e3b0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
1e3c0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
1e3d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
1e3e0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
1e3f0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
1e400 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1e410 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
1e420 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
1e430 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
1e440 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
1e450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1e460 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
1e470 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
1e480 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
1e490 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
1e4a0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
1e4b0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
1e4c0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
1e4d0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
1e4e0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
1e4f0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
1e500 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
1e510 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
1e520 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
1e530 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
1e540 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
1e550 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
1e560 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
1e570 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
1e580 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
1e590 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
1e5a0 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
1e5b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1e5c0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
1e5d0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
1e5e0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
1e5f0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
1e600 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
1e610 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1e620 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
1e630 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e640 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
1e650 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
1e660 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
1e670 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
1e680 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
1e690 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
1e6a0 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
1e6b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1e6c0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
1e6d0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
1e6e0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
1e6f0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
1e700 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
1e710 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
1e720 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
1e730 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
1e740 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
1e750 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
1e760 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
1e770 20 69 64 65 6e 74 69 66 65 72 2e 29 5e 20 20 5e   identifer.)^  ^
1e780 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
1e790 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
1e7a0 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
1e7b0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1e7c0 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
1e7d0 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
1e7e0 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
1e7f0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1e800 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
1e810 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
1e820 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
1e830 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
1e840 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1e850 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
1e860 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
1e870 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1e880 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
1e890 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
1e8a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e8b0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1e8c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
1e8d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1e8e0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1e8f0 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
1e900 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
1e910 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
1e920 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
1e930 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
1e940 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
1e950 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
1e960 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
1e970 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
1e980 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
1e990 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
1e9a0 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
1e9b0 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
1e9c0 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
1e9d0 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
1e9e0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
1e9f0 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
1ea00 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
1ea10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1ea20 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
1ea30 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
1ea40 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
1ea50 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
1ea60 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
1ea70 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
1ea80 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
1ea90 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
1eaa0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
1eab0 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
1eac0 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
1ead0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1eae0 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
1eaf0 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
1eb00 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
1eb10 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
1eb20 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
1eb30 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1eb40 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
1eb50 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
1eb60 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
1eb70 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
1eb80 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1eb90 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
1eba0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
1ebb0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
1ebc0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
1ebd0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
1ebe0 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
1ebf0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
1ec00 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
1ec10 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
1ec20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
1ec30 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
1ec40 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
1ec50 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
1ec60 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
1ec70 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1ec80 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
1ec90 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
1eca0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1ecb0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
1ecc0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1ecd0 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
1ece0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
1ecf0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
1ed00 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
1ed10 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
1ed20 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
1ed30 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
1ed40 65 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66 20  ed with it. ^If 
1ed50 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1ed60 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
1ed70 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
1ed80 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
1ed90 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
1eda0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
1edb0 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
1edc0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
1edd0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
1ede0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
1edf0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
1ee00 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
1ee10 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
1ee20 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
1ee30 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
1ee40 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
1ee50 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
1ee60 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
1ee70 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
1ee80 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1ee90 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1eea0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1eeb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1eec0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
1eed0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
1eee0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
1eef0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
1ef00 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
1ef10 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
1ef20 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
1ef30 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
1ef40 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
1ef50 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
1ef60 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
1ef70 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
1ef80 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
1ef90 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
1efa0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
1efb0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
1efc0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
1efd0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
1efe0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
1eff0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
1f000 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
1f010 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
1f020 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
1f030 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
1f040 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
1f050 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
1f060 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
1f070 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1f080 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
1f090 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1f0a0 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
1f0b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f0c0 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
1f0d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f0e0 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
1f0f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f100 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
1f110 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
1f120 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
1f130 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
1f140 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
1f150 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
1f160 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
1f170 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
1f180 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
1f190 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1f1a0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
1f1b0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
1f1c0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
1f1d0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
1f1e0 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
1f1f0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
1f200 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
1f210 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
1f220 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
1f230 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
1f240 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
1f250 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
1f260 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
1f270 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
1f280 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
1f290 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
1f2a0 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
1f2b0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
1f2c0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
1f2d0 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
1f2e0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
1f2f0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
1f300 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
1f310 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
1f320 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
1f330 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
1f340 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
1f350 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1f360 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1f370 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
1f380 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1f390 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
1f3a0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1f3b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1f3c0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
1f3d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f3e0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1f3f0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
1f400 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1f410 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1f420 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
1f430 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
1f440 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
1f450 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1f460 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
1f470 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
1f480 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f490 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
1f4a0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
1f4b0 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
1f4c0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
1f4d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1f4e0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
1f4f0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
1f500 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1f510 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
1f520 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
1f530 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1f540 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
1f550 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1f560 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1f570 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1f580 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1f590 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
1f5a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1f5b0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
1f5c0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1f5d0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
1f5e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1f5f0 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
1f600 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
1f610 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
1f620 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
1f630 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
1f640 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
1f650 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
1f660 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
1f670 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
1f680 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
1f690 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
1f6a0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
1f6b0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
1f6c0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
1f6d0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
1f6e0 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
1f6f0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
1f700 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
1f710 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
1f720 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
1f730 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
1f740 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
1f750 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
1f760 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
1f770 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
1f780 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
1f790 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
1f7a0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
1f7b0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
1f7c0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
1f7d0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
1f7e0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
1f7f0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
1f800 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
1f810 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
1f820 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
1f830 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
1f840 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
1f850 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1f860 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1f870 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1f880 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1f890 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1f8a0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1f8b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1f8c0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
1f8d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1f8e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1f8f0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
1f900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f910 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
1f920 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
1f930 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1f940 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1f950 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
1f960 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
1f970 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
1f980 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
1f990 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
1f9a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
1f9b0 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
1f9c0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
1f9d0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
1f9e0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
1f9f0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
1fa00 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
1fa10 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
1fa20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
1fa30 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
1fa40 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1fa50 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
1fa60 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
1fa70 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
1fa80 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
1fa90 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
1faa0 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
1fab0 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
1fac0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
1fad0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
1fae0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
1faf0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
1fb00 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
1fb10 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
1fb20 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
1fb30 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
1fb40 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
1fb50 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
1fb60 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
1fb70 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
1fb80 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
1fb90 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
1fba0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
1fbb0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
1fbc0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
1fbd0 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
1fbe0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
1fbf0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
1fc00 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
1fc10 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
1fc20 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
1fc30 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
1fc40 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
1fc50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1fc60 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
1fc70 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1fc80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
1fc90 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1fca0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1fcb0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
1fcc0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1fcd0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
1fce0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
1fcf0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1fd00 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
1fd10 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
1fd20 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1fd30 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1fd40 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
1fd50 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
1fd60 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
1fd70 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
1fd80 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
1fd90 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
1fda0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
1fdb0 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
1fdc0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
1fdd0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
1fde0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
1fdf0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
1fe00 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1fe10 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1fe20 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
1fe30 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
1fe40 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
1fe50 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
1fe60 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
1fe70 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
1fe80 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
1fe90 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
1fea0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1feb0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
1fec0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
1fed0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
1fee0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1fef0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
1ff00 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1ff10 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1ff20 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1ff30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1ff40 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
1ff50 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1ff60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ff70 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
1ff80 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
1ff90 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
1ffa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
1ffb0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
1ffc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ffd0 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
1ffe0 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
1fff0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
20000 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
20010 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
20020 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
20030 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
20040 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
20050 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
20060 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
20070 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
20080 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
20090 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
200a0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
200b0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
200c0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
200d0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
200e0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
200f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20100 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
20110 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
20120 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
20130 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
20140 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
20150 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
20160 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
20170 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20180 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
20190 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
201a0 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
201b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
201c0 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
201d0 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
201e0 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
201f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
20200 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
20210 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
20220 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
20230 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
20240 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
20250 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
20260 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
20270 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
20280 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
20290 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
202a0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
202b0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
202c0 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
202d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
202e0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
202f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
20300 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
20310 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
20320 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
20330 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
20340 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
20350 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
20360 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
20370 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
20380 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
20390 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
203a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
203b0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
203c0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
203d0 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
203e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
203f0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
20400 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
20410 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
20420 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
20430 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
20440 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
20450 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
20460 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
20470 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
20480 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
20490 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
204a0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
204b0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
204c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
204d0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
204e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
204f0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
20500 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
20510 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20520 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
20530 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
20540 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
20550 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
20560 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
20570 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
20580 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
20590 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
205a0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
205b0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
205c0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
205d0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
205e0 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
205f0 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
20600 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
20610 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
20620 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
20630 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
20640 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
20650 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
20660 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
20670 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
20680 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
20690 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
206a0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
206b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
206c0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
206d0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
206e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
206f0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
20700 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
20710 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20720 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
20730 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
20740 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
20750 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
20760 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
20770 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
20780 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
20790 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
207a0 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
207b0 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
207c0 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
207d0 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
207e0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
207f0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
20800 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
20810 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
20820 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
20830 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
20840 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
20850 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
20860 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
20870 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
20880 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
20890 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
208a0 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
208b0 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
208c0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
208d0 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
208e0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
208f0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
20900 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
20910 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
20920 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
20930 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
20940 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
20950 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
20960 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
20970 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
20980 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
20990 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
209a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
209b0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
209c0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
209d0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
209e0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
209f0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
20a00 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
20a10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
20a20 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
20a30 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
20a40 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
20a50 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
20a60 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
20a70 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
20a80 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
20a90 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
20aa0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
20ab0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
20ac0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
20ad0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
20ae0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
20af0 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
20b00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
20b10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
20b20 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
20b30 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
20b40 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
20b50 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
20b60 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
20b70 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
20b80 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
20b90 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
20ba0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
20bb0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
20bc0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
20bd0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
20be0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
20bf0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
20c00 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
20c10 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
20c20 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
20c30 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
20c40 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
20c50 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
20c60 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
20c70 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
20c80 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
20c90 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
20ca0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
20cb0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
20cc0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
20cd0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
20ce0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
20cf0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
20d00 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
20d10 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
20d20 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
20d30 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
20d40 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
20d50 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
20d60 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
20d70 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
20d80 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
20d90 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
20da0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
20db0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
20dc0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
20dd0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
20de0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
20df0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
20e00 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
20e10 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
20e20 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
20e30 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
20e40 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
20e50 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
20e60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
20e70 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
20e80 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
20e90 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
20ea0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
20eb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20ec0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
20ed0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
20ee0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
20ef0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
20f00 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
20f10 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
20f20 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
20f30 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
20f40 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
20f50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
20f60 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
20f70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
20f80 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
20f90 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20fa0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
20fb0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
20fc0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
20fd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
20fe0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
20ff0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
21000 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
21010 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
21020 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
21030 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
21040 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21050 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
21060 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
21070 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21080 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
21090 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
210a0 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
210b0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
210c0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
210d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
210e0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
210f0 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
21100 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
21110 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
21120 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
21130 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
21140 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
21150 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
21160 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
21170 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
21180 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
21190 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
211a0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
211b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
211c0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
211d0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
211e0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
211f0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
21200 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
21210 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
21220 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
21230 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
21240 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
21250 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
21260 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
21270 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
21280 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
21290 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
212a0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
212b0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
212c0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
212d0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
212e0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
212f0 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
21300 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
21310 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
21320 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
21330 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
21340 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
21350 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
21360 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
21370 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
21380 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
21390 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
213a0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
213b0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
213c0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
213d0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
213e0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
213f0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
21400 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
21410 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
21420 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
21430 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
21440 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
21450 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
21460 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
21470 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
21480 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
21490 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
214a0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
214b0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
214c0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
214d0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
214e0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
214f0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
21500 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
21510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
21520 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
21530 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
21540 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
21550 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
21560 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
21570 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
21580 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
21590 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
215a0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
215b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
215c0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
215d0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
215e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
215f0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
21600 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21610 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
21620 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
21630 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
21640 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
21650 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
21660 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
21670 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
21680 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
21690 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
216a0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
216b0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
216c0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
216d0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
216e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
216f0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
21700 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
21710 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
21720 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
21730 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
21740 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
21750 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21760 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
21770 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
21780 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
21790 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
217a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
217b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
217c0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
217d0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
217e0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
217f0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
21800 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
21810 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
21820 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
21830 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
21840 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
21850 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
21860 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
21870 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
21880 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
21890 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
218a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
218b0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
218c0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
218d0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
218e0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
218f0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
21900 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
21910 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
21920 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
21930 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
21940 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
21950 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
21960 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
21970 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
21980 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
21990 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
219a0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
219b0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
219c0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
219d0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
219e0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
219f0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
21a00 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
21a10 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
21a20 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
21a30 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
21a40 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
21a50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
21a60 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
21a70 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
21a80 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
21a90 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
21aa0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
21ab0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
21ac0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
21ad0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
21ae0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
21af0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
21b00 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
21b10 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
21b20 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
21b30 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
21b40 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
21b50 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
21b60 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
21b70 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
21b80 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
21b90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
21ba0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
21bb0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
21bc0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
21bd0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
21be0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
21bf0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
21c00 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
21c10 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
21c20 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
21c30 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
21c40 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
21c50 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
21c60 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
21c70 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
21c80 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
21c90 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
21ca0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
21cb0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
21cc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
21cd0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
21ce0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
21cf0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
21d00 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
21d10 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
21d20 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
21d30 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
21d40 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
21d50 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
21d60 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
21d70 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
21d80 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
21d90 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
21da0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
21db0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
21dc0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
21dd0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
21de0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
21df0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
21e00 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
21e10 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
21e20 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
21e30 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
21e40 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
21e50 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
21e60 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
21e70 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
21e80 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
21e90 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
21ea0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
21eb0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
21ec0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
21ed0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
21ee0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
21ef0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
21f00 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
21f10 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
21f20 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
21f30 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
21f40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
21f50 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
21f60 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
21f70 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
21f80 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
21f90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
21fa0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
21fb0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
21fc0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
21fd0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
21fe0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
21ff0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
22000 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
22010 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
22020 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
22030 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
22040 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
22050 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
22060 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
22070 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
22080 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
22090 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
220a0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
220b0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
220c0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
220d0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
220e0 20 69 74 20 77 61 73 20 72 65 71 75 69 72 65 64   it was required
220f0 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c 69 74 65  .** after sqlite
22100 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
22110 64 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  d anything other
22120 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
22130 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  W] that.** [sqli
22140 74 65 33 5f 72 65 73 65 74 28 29 5d 20 62 65 20  te3_reset()] be 
22150 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 61 6e  called before an
22160 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
22170 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
22180 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
22190 61 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f 6b 65  ailure to invoke
221a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
221b0 29 5d 20 69 6e 20 74 68 69 73 20 77 61 79 20 77  )] in this way w
221c0 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ould.** result i
221d0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
221e0 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
221f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
22200 20 20 42 75 74 20 61 66 74 65 72 0a 2a 2a 20 76    But after.** v
22210 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
22220 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
22230 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20 5b 73  began calling [s
22240 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22250 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
22260 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
22270 73 74 61 6e 63 65 20 72 61 74 68 65 72 20 74 68  stance rather th
22280 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
22290 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 0a  LITE_MISUSE].  .
222a0 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
222b0 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
222c0 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
222d0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
222e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
222f0 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
22300 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
22310 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
22320 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
22330 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
22340 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
22350 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
22360 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
22370 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
22380 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
22390 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
223a0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
223b0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
223c0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
223d0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
223e0 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
223f0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
22400 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
22410 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
22420 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
22430 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
22440 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
22450 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
22460 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
22470 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
22480 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
22490 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
224a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
224b0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
224c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
224d0 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
224e0 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
224f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
22500 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
22510 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
22520 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
22530 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
22540 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
22550 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
22560 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
22570 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
22580 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
22590 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
225a0 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
225b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
225c0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
225d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
225e0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
225f0 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
22600 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22610 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
22620 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
22630 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
22640 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
22650 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
22660 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f  statement] P..*/
22670 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
22680 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
22690 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
226a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
226b0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
226c0 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
226d0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
226e0 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
226f0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
22700 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
22710 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
22720 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
22730 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
22740 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
22750 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
22760 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
22770 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
22780 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
22790 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
227a0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
227b0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
227c0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
227d0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
227e0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
227f0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
22800 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
22810 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
22820 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
22830 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
22840 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
22850 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
22860 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
22870 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
22880 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
22890 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
228a0 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
228b0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
228c0 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
228d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
228e0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
228f0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
22900 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
22910 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
22920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
22930 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
22940 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
22950 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
22960 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
22970 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
22980 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
22990 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
229a0 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
229b0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
229c0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
229d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
229e0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
229f0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
22a00 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
22a10 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
22a20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
22a30 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
22a40 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
22a50 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
22a60 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
22a70 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
22a80 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
22a90 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
22aa0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
22ab0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
22ac0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
22ad0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22ae0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
22af0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
22b00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
22b10 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
22b20 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
22b30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
22b40 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
22b50 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
22b60 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
22b70 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
22b80 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
22b90 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
22ba0 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
22bb0 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
22bc0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
22bd0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
22be0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
22bf0 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
22c00 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
22c10 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
22c20 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
22c30 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
22c40 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
22c50 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
22c60 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
22c70 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
22c80 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
22c90 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
22ca0 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
22cb0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
22cc0 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
22cd0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
22ce0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
22cf0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
22d00 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
22d10 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
22d20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
22d30 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
22d40 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
22d50 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
22d60 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
22d70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22d80 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
22d90 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
22da0 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
22db0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
22dc0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
22dd0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22de0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
22df0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
22e00 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
22e10 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
22e20 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
22e30 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
22e40 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
22e50 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
22e60 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
22e70 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
22e80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
22e90 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
22ea0 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
22eb0 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
22ec0 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
22ed0 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
22ee0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
22ef0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
22f00 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
22f10 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
22f20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
22f30 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
22f40 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
22f50 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
22f60 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
22f70 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
22f80 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
22f90 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
22fa0 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
22fb0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
22fc0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
22fd0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
22fe0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
22ff0 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
23000 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
23010 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
23020 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
23030 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
23040 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
23050 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
23060 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
23070 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
23080 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
23090 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
230a0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
230b0 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
230c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
230d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
230e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
230f0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
23100 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
23110 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
23120 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
23130 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
23140 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
23150 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
23160 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
23170 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
23180 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
23190 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
231a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
231b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
231c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
231d0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
231e0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
231f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
23200 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
23210 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
23220 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
23230 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
23240 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
23250 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
23260 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
23270 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
23280 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
23290 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
232a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
232b0 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
232c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
232d0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
232e0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
232f0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
23300 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
23310 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
23320 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
23330 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
23340 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
23350 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
23360 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20  rminator at the 
23370 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
23380 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
23390 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
233a0 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
233b0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
233c0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
233d0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
233e0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
233f0 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
23400 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
23410 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
23420 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
23430 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
23440 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
23450 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
23460 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
23470 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
23480 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
23490 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
234a0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
234b0 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72  th BLOB is an ar
234c0 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74  bitrary.** point
234d0 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65  er, possibly eve
234e0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
234f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
23500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23510 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73  s16() routine is
23520 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69   similar to sqli
23530 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
23540 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73  ().** but leaves
23550 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55   the result in U
23560 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20  TF-16 in native 
23570 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65  byte order inste
23580 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20  ad of UTF-8..** 
23590 5e 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ^The zero termin
235a0 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c  ator is not incl
235b0 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75  uded in this cou
235c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  nt..**.** ^The o
235d0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
235e0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
235f0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
23600 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
23610 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
23620 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
23630 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23640 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
23650 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
23660 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
23670 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
23680 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
23690 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
236a0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
236b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
236c0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
236d0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
236e0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
236f0 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
23700 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
23710 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
23720 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
23730 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
23740 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
23750 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
23760 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
23770 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
23780 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
23790 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
237a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
237b0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
237c0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
237d0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
237e0 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
237f0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
23800 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
23810 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
23820 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
23830 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
23840 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
23850 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
23860 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
23870 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
23880 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
23890 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
238a0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
238b0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
238c0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
238d0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
238e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
238f0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
23900 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
23910 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
23920 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
23930 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
23940 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
23950 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
23960 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
23970 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
23980 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
23990 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
239a0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
239b0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
239c0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
239d0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
239e0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
239f0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
23a00 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
23a10 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
23a20 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
23a30 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
23a40 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
23a50 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
23a60 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
23a70 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
23a80 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
23a90 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
23aa0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
23ab0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
23ac0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
23ad0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
23ae0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
23af0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
23b00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
23b10 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
23b20 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
23b30 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
23b40 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
23b50 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
23b60 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
23b70 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
23b80 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
23b90 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
23ba0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
23bb0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
23bc0 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
23bd0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
23be0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
23bf0 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
23c00 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
23c10 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
23c20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
23c30 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
23c40 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
23c50 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
23c60 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
23c70 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
23c80 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
23c90 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
23ca0 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
23cb0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
23cc0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
23cd0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
23ce0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
23cf0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
23d00 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
23d10 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
23d20 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
23d30 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
23d40 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
23d50 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
23d60 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
23d70 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
23d80 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
23d90 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
23da0 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
23db0 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
23dc0 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
23dd0 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
23de0 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
23df0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
23e00 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
23e10 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
23e20 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
23e30 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
23e40 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
23e50 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
23e60 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
23e70 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
23e80 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
23e90 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  rs..**.** ^Note 
23ea0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
23eb0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
23ec0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
23ed0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
23ee0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
23ef0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
23f00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23f10 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
23f20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23f30 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
23f40 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
23f50 5e 28 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  ^(Type conversio
23f60 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
23f70 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
23f80 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
23f90 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
23fa0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
23fb0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
23fc0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
23fd0 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
23fe0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
23ff0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
24000 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
24010 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
24020 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
24030 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
24040 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
24050 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
24060 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
24070 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
24080 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
24090 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
240a0 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
240b0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
240c0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
240d0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
240e0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
240f0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
24100 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
24110 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
24120 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
24130 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
24140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24150 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
24160 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24170 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
24180 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
24190 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
241a0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
241b0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29  .</li>.** </ul>)
241c0 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  ^.**.** ^Convers
241d0 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
241e0 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
241f0 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
24200 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
24210 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
24220 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
24230 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
24240 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
24250 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
24260 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
24270 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74  or pointer point
24280 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62  s to will have b
24290 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
242a0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
242b0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
242c0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
242d0 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
242e0 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
242f0 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
24300 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
24310 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
24320 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
24330 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
24340 2a 2a 20 5e 28 54 68 65 20 73 61 66 65 73 74 20  ** ^(The safest 
24350 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
24360 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
24370 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
24380 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
24390 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
243a0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
243b0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
243c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
243d0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
243e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
243f0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
24400 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
24410 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
24420 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
24430 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
24440 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
24450 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
24460 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
24470 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24480 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
24490 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e  </ul>)^.**.** In
244a0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
244b0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
244c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
244d0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
244e0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
244f0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
24500 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
24510 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
24520 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
24530 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
24540 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
24550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24560 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
24570 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
24580 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
24590 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
245a0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
245b0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
245c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
245d0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
245e0 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
245f0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
24600 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
24610 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
24620 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
24630 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
24640 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
24650 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
24660 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
24670 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
24680 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
24690 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
246a0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
246b0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
246c0 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
246d0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
246e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
246f0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
24700 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
24710 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
24720 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
24730 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
24740 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
24750 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
24760 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
24770 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
24780 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
24790 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
247a0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
247b0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
247c0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
247d0 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
247e0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
247f0 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
24800 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
24810 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
24820 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
24830 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
24840 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
24850 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
24860 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
24870 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
24880 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
24890 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
248a0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
248b0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
248c0 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
248d0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
248e0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
248f0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
24900 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
24910 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
24920 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
24930 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
24940 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24950 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
24960 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
24970 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
24980 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
24990 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
249a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
249b0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
249c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
249d0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
249e0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
249f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
24a00 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
24a10 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24a20 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
24a30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
24a40 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
24a50 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
24a60 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
24a70 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
24a80 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
24a90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24aa0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
24ab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24ac0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
24ad0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
24ae0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24af0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
24b00 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
24b10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
24b20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
24b30 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
24b40 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
24b50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
24b60 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
24b70 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
24b80 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
24b90 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
24ba0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
24bb0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
24bc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24bd0 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
24be0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78  statement was ex
24bf0 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75  ecuted successfu
24c00 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75  lly or not execu
24c10 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e  ted at all, then
24c20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  .** SQLITE_OK is
24c30 20 72 65 74 75 72 6e 65 64 2e 20 5e 49 66 20 65   returned. ^If e
24c40 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
24c50 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64  statement failed
24c60 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72   then an.** [err
24c70 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  or code] or [ext
24c80 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
24c90 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
24ca0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
24cb0 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
24cc0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
24cd0 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ring the executi
24ce0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72  on of the.** [pr
24cf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24d00 5d 2e 20 20 5e 49 66 20 74 68 65 20 76 69 72 74  ].  ^If the virt
24d10 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20  ual machine has 
24d20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  not.** completed
24d30 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20   execution when 
24d40 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
24d50 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20  called, that is 
24d60 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  like.** encounte
24d70 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72  ring an error or
24d80 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
24d90 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
24da0 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c  pt]..** ^Incompl
24db0 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20  ete updates may 
24dc0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
24dd0 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  nd transactions 
24de0 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70  canceled,.** dep
24df0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69  ending on the ci
24e00 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64  rcumstances, and
24e10 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63   the.** [error c
24e20 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69  ode] returned wi
24e30 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42  ll be [SQLITE_AB
24e40 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ORT]..*/.int sql
24e50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
24e60 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
24e70 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
24e80 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
24e90 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
24ea0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
24eb0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
24ec0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
24ed0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
24ee0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24ef0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
24f00 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
24f10 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
24f20 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
24f30 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
24f40 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
24f50 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
24f60 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
24f70 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
24f80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
24f90 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
24fa0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
24fb0 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
24fc0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
24fd0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
24fe0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
24ff0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
25000 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25010 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
25020 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
25030 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
25040 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
25050 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
25060 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
25070 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
25080 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
25090 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
250a0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
250b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
250c0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
250d0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
250e0 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
250f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
25100 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
25110 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
25120 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
25130 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
25140 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
25150 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
25160 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
25170 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
25180 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
25190 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
251a0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
251b0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
251c0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
251d0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
251e0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
251f0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
25200 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
25210 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
25220 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
25230 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
25240 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
25250 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
25260 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
25270 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25280 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
25290 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
252a0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
252b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
252c0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
252d0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
252e0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
252f0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
25300 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
25310 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
25320 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25330 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
25340 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
25350 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25360 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
25370 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 74 77 6f  **.** ^These two
25380 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
25390 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
253a0 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
253b0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
253c0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
253d0 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
253e0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
253f0 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
25400 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
25410 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
25420 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
25430 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
25440 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77   difference betw
25450 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69  een the.** two i
25460 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
25470 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  d parameter, the
25480 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63   name of the (sc
25490 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f  alar) function o
254a0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20  r.** aggregate, 
254b0 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  is encoded in UT
254c0 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  F-8 for sqlite3_
254d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
254e0 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20  ) and UTF-16.** 
254f0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
25500 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e  te_function16().
25510 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
25520 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
25530 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
25540 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
25550 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
25560 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
25570 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
25580 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
25590 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
255a0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
255b0 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
255c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
255d0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
255e0 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
255f0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
25600 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
25610 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ly..**.** The se
25620 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
25630 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
25640 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
25650 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
25660 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
25670 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
25680 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
25690 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
256a0 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20  exclusive of.** 
256b0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
256c0 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  tor.  Note that 
256d0 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20  the name length 
256e0 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65  limit is in byte
256f0 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63  s, not.** charac
25700 74 65 72 73 2e 20 20 5e 41 6e 79 20 61 74 74 65  ters.  ^Any atte
25710 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
25720 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
25730 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
25740 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
25750 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69  QLITE_ERROR] bei
25760 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
25770 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
25780 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
25790 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
257a0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
257b0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
257c0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
257d0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
257e0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
257f0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
25800 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
25810 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
25820 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
25830 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
25840 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
25850 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
25860 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
25870 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
25880 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
25890 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
258a0 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
258b0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
258c0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
258d0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
258e0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
258f0 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
25900 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
25910 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
25920 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
25930 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
25940 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
25950 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
25960 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
25970 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
25980 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
25990 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
259a0 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
259b0 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
259c0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
259d0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
259e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
259f0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
25a00 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
25a10 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
25a20 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
25a30 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
25a40 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
25a50 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25a60 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
25a70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
25a80 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
25a90 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
25aa0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
25ab0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
25ac0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
25ad0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
25ae0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
25af0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
25b00 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
25b10 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
25b20 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
25b30 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
25b40 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
25b50 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
25b60 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
25b70 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
25b80 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
25b90 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
25ba0 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
25bb0 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
25bc0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
25bd0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
25be0 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
25bf0 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
25c00 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
25c10 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
25c20 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
25c30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25c40 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
25c50 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
25c60 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
25c70 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
25c80 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
25c90 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65  ^.**.** The seve
25ca0 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20  nth, eighth and 
25cb0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73  ninth parameters
25cc0 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
25cd0 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
25ce0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
25cf0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
25d00 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
25d10 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
25d20 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
25d30 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
25d40 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
25d50 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
25d60 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
25d70 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
25d80 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
25d90 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  rs should be pas
25da0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
25db0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
25dc0 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
25dd0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
25de0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
25df0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
25e00 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
25e10 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
25e20 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
25e30 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
25e40 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
25e50 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
25e60 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
25e70 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20  , pass NULL for 
25e80 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
25e90 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  on callbacks..**
25ea0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
25eb0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
25ec0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
25ed0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
25ee0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
25ef0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
25f00 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
25f10 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
25f20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
25f30 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
25f40 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
25f50 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
25f60 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
25f70 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
25f80 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
25f90 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
25fa0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
25fb0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
25fc0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
25fd0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
25fe0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
25ff0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
26000 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
26010 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
26020 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
26030 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
26040 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
26050 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
26060 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
26070 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
26080 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
26090 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
260a0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
260b0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
260c0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
260d0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
260e0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
260f0 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
26100 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
26110 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
26120 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
26130 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
26140 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
26150 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
26160 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
26170 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
26180 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
26190 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
261a0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
261b0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
261c0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
261d0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
261e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
261f0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
26200 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
26210 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  ned function wit
26220 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f  h a given name o
26230 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20  verrides all.** 
26240 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  built-in functio
26250 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b  ns in the same [
26260 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26270 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61  ion] with the sa
26280 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62  me name..** ^Sub
26290 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74  sequent applicat
262a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
262b0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
262c0 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72  e name only over
262d0 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61  ride .** prior a
262e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
262f0 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ed functions tha
26300 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d  t are an exact m
26310 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20  atch for the.** 
26320 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
26330 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72 72  ters and preferr
26340 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  ed encoding..**.
26350 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
26360 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26370 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
26380 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
26390 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
263a0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
263b0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
263c0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
263d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
263e0 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
263f0 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
26400 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
26410 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
26420 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
26430 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
26440 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26450 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
26460 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
26470 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
26480 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
26490 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
264a0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
264b0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
264c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
264d0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
264e0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
264f0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
26500 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
26510 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
26520 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
26530 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
26540 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
26550 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
26560 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
26570 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
26580 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
26590 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
265a0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
265b0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
265c0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
265d0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
265e0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
265f0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
26600 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
26610 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
26620 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
26630 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
26640 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ext*).);../*.** 
26650 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
26660 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
26670 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
26680 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
26690 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
266a0 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
266b0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
266c0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
266d0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
266e0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
266f0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
26700 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
26710 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
26720 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
26730 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
26740 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
26750 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
26760 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
26770 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
26780 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
26790 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
267a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
267b0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
267c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
267d0 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
267e0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
267f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
26800 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
26810 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
26820 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
26830 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
26840 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
26850 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
26860 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
26870 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
26880 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
26890 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
268a0 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
268b0 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
268c0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
268d0 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
268e0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
268f0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
26900 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
26910 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
26920 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
26930 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
26940 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
26950 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
26960 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
26970 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
26980 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
26990 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
269a0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
269b0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
269c0 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
269d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
269e0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
269f0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
26a00 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
26a10 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
26a20 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
26a30 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
26a40 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
26a50 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
26a60 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
26a70 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
26a80 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
26a90 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
26aa0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
26ab0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
26ac0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
26ad0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
26ae0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
26af0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
26b00 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
26b10 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
26b20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
26b30 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
26b40 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
26b50 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
26b60 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
26b70 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
26b80 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
26b90 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
26ba0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
26bb0 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
26bc0 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
26bd0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
26be0 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
26bf0 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
26c00 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
26c10 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
26c20 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
26c30 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
26c40 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
26c50 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
26c60 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
26c70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26c80 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
26c90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26ca0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
26cb0 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
26cc0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
26cd0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
26ce0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
26cf0 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72  ..** The 4th par
26d00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
26d10 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
26d20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
26d30 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
26d40 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26d50 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
26d60 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
26d70 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
26d80 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
26d90 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
26da0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
26db0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
26dc0 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
26dd0 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
26de0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
26df0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
26e00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
26e10 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
26e20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26e30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
26e40 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
26e50 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
26e60 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
26e70 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26e80 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
26e90 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
26ea0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
26eb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
26ec0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
26ed0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
26ee0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
26ef0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
26f00 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
26f10 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
26f20 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
26f30 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
26f40 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
26f50 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
26f60 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
26f70 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
26f80 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
26f90 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
26fa0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26fb0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
26fc0 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
26fd0 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
26fe0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
26ff0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
27000 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
27010 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
27020 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27030 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
27040 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
27050 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
27060 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
27070 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
27080 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
27090 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
270a0 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
270b0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
270c0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
270d0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
270e0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
270f0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
27100 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
27110 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
27120 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
27130 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
27140 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
27150 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
27160 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
27170 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
27180 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
27190 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
271a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
271b0 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
271c0 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
271d0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
271e0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
271f0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
27200 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
27210 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
27220 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
27230 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
27240 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
27250 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
27260 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
27270 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
27280 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
27290 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
272a0 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
272b0 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
272c0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
272d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
272e0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
272f0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
27300 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
27310 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
27320 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
27330 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
27340 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
27350 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
27360 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
27370 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
27380 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27390 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
273a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
273b0 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
273c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
273d0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
273e0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
273f0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
27400 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
27410 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
27420 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
27430 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
27440 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
27450 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
27460 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
27470 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
27480 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
27490 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
274a0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
274b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
274c0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
274d0 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
274e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
274f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
27500 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
27510 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
27520 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
27530 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
27540 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
27550 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
27560 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
27570 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
27580 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
27590 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
275a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
275b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
275c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
275d0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
275e0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
275f0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
27600 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
27610 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
27620 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
27630 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27640 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
27650 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
27660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27680 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
27690 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
276a0 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
276b0 65 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  entions of aggre
276c0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
276d0 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
276e0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
276f0 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
27700 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
27710 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
27720 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
27730 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27740 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
27750 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
27760 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
27770 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
27780 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
27790 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
277a0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
277b0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
277c0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
277d0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
277e0 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
277f0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
27800 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
27810 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
27820 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
27830 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
27840 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
27850 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
27860 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
27870 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
27880 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27890 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
278a0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
278b0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
278c0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
278d0 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
278e0 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
278f0 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
27900 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
27910 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
27920 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
27930 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
27940 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
27950 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
27960 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
27970 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
27980 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
27990 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
279a0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
279b0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
279c0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
279d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
279e0 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
279f0 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
27a00 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
27a10 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
27a20 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
27a30 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
27a40 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
27a50 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
27a60 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
27a70 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
27a80 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
27a90 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
27aa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
27ab0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
27ac0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
27ad0 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
27ae0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
27af0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
27b00 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
27b10 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
27b20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
27b30 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
27b40 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
27b50 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
27b60 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
27b70 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
27b80 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27b90 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
27ba0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
27bb0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
27bc0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
27bd0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
27be0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
27bf0 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
27c00 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
27c10 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
27c20 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
27c30 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
27c40 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
27c50 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
27c60 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
27c70 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
27c80 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
27c90 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
27ca0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
27cb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
27cc0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
27cd0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
27ce0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
27cf0 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
27d00 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
27d10 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
27d20 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
27d30 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
27d40 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
27d50 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
27d60 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
27d70 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
27d80 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
27d90 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
27da0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
27db0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
27dc0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
27dd0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
27de0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
27df0 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
27e00 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
27e10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27e20 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
27e30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
27e40 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
27e50 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
27e60 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
27e70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
27e80 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
27e90 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
27ea0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
27eb0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
27ec0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
27ed0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
27ee0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
27ef0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
27f00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
27f10 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
27f20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
27f30 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
27f40 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
27f50 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
27f60 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
27f70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
27f80 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
27f90 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
27fa0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
27fb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
27fc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27fd0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
27fe0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
27ff0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
28000 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
28010 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
28020 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
28030 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
28040 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
28050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
28060 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
28070 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
28080 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28090 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
280a0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
280b0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
280c0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
280d0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
280e0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
280f0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
28100 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
28110 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
28120 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
28130 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
28140 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28150 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
28160 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
28170 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
28180 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
28190 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
281a0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
281b0 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
281c0 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
281d0 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
281e0 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
281f0 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
28200 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
28210 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
28220 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
28230 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
28240 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
28250 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
28260 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
28270 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
28280 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
28290 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
282a0 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
282b0 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
282c0 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
282d0 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
282e0 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
282f0 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
28300 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
28310 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
28320 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
28330 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
28340 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
28350 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
28360 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
28370 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
28380 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
28390 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
283a0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
283b0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
283c0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
283d0 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
283e0 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
283f0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
28400 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
28410 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
28420 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
28430 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
28440 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
28450 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
28460 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
28470 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
28480 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
28490 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
284a0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
284b0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
284c0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
284d0 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
284e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
284f0 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f  function. ^If no
28500 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
28510 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
28520 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
28530 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
28540 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
28550 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
28560 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
28570 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
28580 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
28590 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
285a0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
285b0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
285c0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
285d0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
285e0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
285f0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
28600 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
28610 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
28620 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
28630 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
28640 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
28650 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
28660 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
28670 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
28680 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
28690 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
286a0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
286b0 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
286c0 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
286d0 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
286e0 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
286f0 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  ^If it is not NU
28700 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
28710 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
28720 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
28730 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
28740 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
28750 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
28760 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
28770 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
28780 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
28790 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
287a0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
287b0 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
287c0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
287d0 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
287e0 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
287f0 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
28800 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
28810 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
28820 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
28830 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
28840 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
28850 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f  ny time.  ^The o
28860 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
28870 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
28880 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
28890 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
288a0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
288b0 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  opped..**.** ^(I
288c0 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
288d0 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
288e0 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
288f0 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
28900 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
28910 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
28920 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
28930 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
28940 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
28950 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e  nd [parameters].
28960 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
28970 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
28980 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
28990 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
289a0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
289b0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
289c0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
289d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
289e0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
289f0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
28a00 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
28a10 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
28a20 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
28a30 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
28a40 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
28a50 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
28a60 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
28a70 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
28a80 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
28a90 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
28aa0 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
28ab0 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
28ac0 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
28ad0 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
28ae0 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
28af0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
28b00 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
28b10 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
28b20 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
28b30 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
28b40 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
28b50 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
28b60 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
28b70 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
28b80 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
28b90 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
28ba0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
28bb0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
28bc0 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
28bd0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
28be0 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
28bf0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
28c00 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
28c10 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
28c20 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
28c30 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
28c40 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
28c50 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
28c60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
28c70 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
28c80 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
28c90 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
28ca0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
28cb0 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
28cc0 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
28cd0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
28ce0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
28cf0 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
28d00 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
28d10 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
28d20 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
28d30 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
28d40 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
28d50 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
28d60 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
28d70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
28d80 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
28d90 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
28da0 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
28db0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
28dc0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
28dd0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
28de0 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
28df0 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
28e00 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
28e10 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
28e20 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
28e30 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
28e40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
28e50 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
28e60 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
28e70 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
28e80 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
28e90 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
28ea0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
28eb0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
28ec0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
28ed0 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
28ee0 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
28ef0 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
28f00 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
28f10 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
28f20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
28f30 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
28f40 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
28f50 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
28f60 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
28f70 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
28f80 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
28f90 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
28fa0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28fb0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
28fc0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
28fd0 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
28fe0 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
28ff0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
29000 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
29010 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
29020 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
29030 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
29040 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29050 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
29060 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
29070 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
29080 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
29090 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
290a0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
290b0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
290c0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
290d0 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
290e0 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
290f0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
29100 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
29110 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29120 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
29130 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
29140 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
29150 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
29160 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29170 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
29180 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
29190 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
291a0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
291b0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
291c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
291d0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
291e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
291f0 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
29200 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
29210 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
29220 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
29230 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
29240 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
29250 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
29260 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
29270 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
29280 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
29290 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
292a0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
292b0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
292c0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
292d0 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
292e0 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
292f0 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
29300 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
29310 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
29320 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
29330 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
29340 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
29350 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29360 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
29370 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
29380 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
29390 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
293a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
293b0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
293c0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
293d0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
293e0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
293f0 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
29400 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
29410 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
29420 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
29430 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
29440 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
29450 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
29460 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29470 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
29480 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
29490 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
294a0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
294b0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
294c0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
294d0 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
294e0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
294f0 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
29500 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
29510 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29520 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
29530 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
29540 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
29550 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
29560 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
29570 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
29580 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
29590 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
295a0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
295b0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
295c0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
295d0 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
295e0 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
295f0 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
29600 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29610 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
29620 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
29630 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
29640 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
29650 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
29660 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
29670 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
29680 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
29690 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
296a0 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
296b0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
296c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
296d0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
296e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
296f0 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
29700 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
29710 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
29720 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29730 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e  sult_toobig() in
29740 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
29750 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
29760 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
29770 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
29780 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
29790 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
297a0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
297b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
297c0 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
297d0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
297e0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
297f0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
29800 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
29810 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
29820 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29830 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
29840 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
29850 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
29860 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
29870 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
29880 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
29890 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
298a0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
298b0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
298c0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
298d0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
298e0 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
298f0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
29900 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
29910 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29920 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
29930 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
29940 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
29950 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
29960 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
29970 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
29980 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29990 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
299a0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
299b0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
299c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
299d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
299e0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
299f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29a00 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
29a10 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
29a20 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
29a30 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
29a40 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
29a50 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
29a60 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
29a70 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
29a80 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
29a90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
29aa0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
29ab0 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
29ac0 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
29ad0 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
29ae0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
29af0 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
29b00 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
29b10 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
29b20 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
29b30 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ely..** ^SQLite 
29b40 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
29b50 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
29b60 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
29b70 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
29b80 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
29b90 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
29ba0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
29bb0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
29bc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
29bd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
29be0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
29bf0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
29c00 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
29c10 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
29c20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
29c30 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
29c40 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
29c50 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
29c60 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
29c70 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
29c80 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
29c90 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
29ca0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
29cb0 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
29cc0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
29cd0 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
29ce0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
29cf0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
29d00 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
29d10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29d20 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
29d30 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
29d40 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
29d50 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
29d60 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
29d70 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
29d80 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
29d90 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
29da0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
29db0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
29dc0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
29dd0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
29de0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
29df0 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
29e00 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
29e10 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
29e20 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
29e30 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
29e40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29e50 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
29e60 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
29e70 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
29e80 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
29e90 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
29ea0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
29eb0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
29ec0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
29ed0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
29ee0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
29ef0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
29f00 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
29f10 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
29f20 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
29f30 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
29f40 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
29f50 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
29f60 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
29f70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
29f80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
29f90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29fa0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
29fb0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
29fc0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
29fd0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
29fe0 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
29ff0 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
2a000 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
2a010 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
2a020 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
2a030 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
2a040 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2a050 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
2a060 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
2a070 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a080 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
2a090 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2a0a0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
2a0b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a0c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2a0d0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
2a0e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a0f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2a100 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2a110 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
2a120 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
2a130 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2a140 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
2a150 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
2a160 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
2a170 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
2a180 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
2a190 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
2a1a0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
2a1b0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
2a1c0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
2a1d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2a1e0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
2a1f0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
2a200 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2a210 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2a220 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
2a230 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
2a240 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2a250 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a260 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
2a270 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
2a280 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
2a290 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
2a2a0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
2a2b0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
2a2c0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
2a2d0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2a2e0 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
2a2f0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2a300 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
2a310 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2a320 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a330 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
2a340 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
2a350 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
2a360 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
2a370 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2a380 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
2a390 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a3a0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
2a3b0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2a3c0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2a3d0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2a3e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
2a3f0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
2a400 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
2a410 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a420 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
2a430 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2a440 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
2a450 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2a460 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
2a470 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2a480 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
2a490 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a4a0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
2a4b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a4c0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2a4d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
2a4e0 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
2a4f0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
2a500 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a510 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
2a520 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
2a530 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a540 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
2a550 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
2a560 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a570 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
2a580 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
2a590 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
2a5a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2a5b0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
2a5c0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2a5d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
2a5e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a5f0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
2a600 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2a610 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2a620 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
2a630 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a640 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2a650 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2a660 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2a670 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2a680 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a690 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2a6a0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2a6b0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2a6c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
2a6d0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2a6e0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2a6f0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
2a700 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2a710 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2a720 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a730 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
2a740 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2a750 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
2a760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a770 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
2a780 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
2a790 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
2a7a0 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
2a7b0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2a7c0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
2a7d0 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
2a7e0 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a  quences to the.*
2a7f0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
2a800 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
2a810 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
2a820 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2a830 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2a840 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
2a850 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66  quence is specif
2a860 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73  ied as a UTF-8 s
2a870 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
2a880 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a890 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
2a8a0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2a8b0 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
2a8c0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2a8d0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
2a8e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2a8f0 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65 73  ). ^In all cases
2a900 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20  .** the name is 
2a910 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
2a920 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2a930 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2a940 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2a950 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
2a960 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
2a970 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
2a980 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2a990 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2a9a0 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16BE], indicatin
2a9b0 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d  g that the user-
2a9c0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74  supplied.** rout
2a9d0 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62  ine expects to b
2a9e0 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72  e passed pointer
2a9f0 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63  s to strings enc
2aa00 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
2aa10 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
2aa20 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le-endian, or UT
2aa30 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c  F-16 big-endian,
2aa40 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 5e   respectively. ^
2aa50 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  The.** third arg
2aa60 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f  ument might also
2aa70 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
2aa80 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  6] to indicate t
2aa90 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a  hat the routine.
2aaa0 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ** expects point
2aab0 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36  ers to be UTF-16
2aac0 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
2aad0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2aae0 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67  r, or the.** arg
2aaf0 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51  ument can be [SQ
2ab00 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2ab10 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68  ED] if the.** th
2ab20 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  e routine expect
2ab30 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36  s pointers to 16
2ab40 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65  -bit word aligne
2ab50 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20  d strings.** of 
2ab60 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
2ab70 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
2ab80 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
2ab90 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
2aba0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
2abb0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2abc0 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
2abd0 75 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74 20 69  ument.  ^If it i
2abe0 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20  s NULL, this is 
2abf0 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65  the same as dele
2ac00 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69  ting the collati
2ac10 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28  on.** sequence (
2ac20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  so that SQLite c
2ac30 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e  annot call it an
2ac40 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63 68  ymore)..** ^Each
2ac50 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63   time the applic
2ac60 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66  ation supplied f
2ac70 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
2ac80 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64  ed, it is passed
2ac90 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74  .** as its first
2aca0 20 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70   parameter a cop
2acb0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
2acc0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
2acd0 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
2ace0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
2acf0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72  e_collation() or
2ad00 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ad10 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
2ad20 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69 6e  *.** ^The remain
2ad30 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
2ad40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2ad50 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e  -supplied routin
2ad60 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67  e are two string
2ad70 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65  s,.** each repre
2ad80 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e  sented by a (len
2ad90 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20  gth, data) pair 
2ada0 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74  and encoded in t
2adb0 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74  he encoding.** t
2adc0 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61  hat was passed a
2add0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
2ade0 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f  ment when the co
2adf0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2ae00 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72   was.** register
2ae10 65 64 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ed.  The applica
2ae20 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c  tion defined col
2ae30 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73  lation routine s
2ae40 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
2ae50 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f  negative, zero o
2ae60 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68  r positive if th
2ae70 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
2ae80 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20  s less than,.** 
2ae90 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
2aea0 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
2aeb0 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65  cond string. i.e
2aec0 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52  . (STRING1 - STR
2aed0 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ING2)..**.** ^Th
2aee0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2aef0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
2af00 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
2af10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2af20 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  ion().** except 
2af30 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e  that it takes an
2af40 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20   extra argument 
2af50 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72  which is a destr
2af60 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65  uctor for.** the
2af70 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e 54 68   collation.  ^Th
2af80 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2af90 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
2afa0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  collation is.** 
2afb0 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73  destroyed and is
2afc0 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f   passed a copy o
2afd0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2afe0 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69  ameter void* poi
2aff0 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73  nter.** of the s
2b000 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2b010 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  llation_v2()..**
2b020 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65   ^Collations are
2b030 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20   destroyed when 
2b040 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
2b050 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
2b060 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c  ls to the.** col
2b070 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
2b080 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
2b090 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
2b0a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
2b0b0 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  losed.** using [
2b0c0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2b0d0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2b0e0 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
2b0f0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
2b100 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2b110 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2b120 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2b130 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b140 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
2b150 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
2b160 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
2b170 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
2b180 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
2b190 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
2b1a0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
2b1b0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  st void*).);.int
2b1c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b1d0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
2b1e0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2b1f0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
2b200 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2b210 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
2b220 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2b230 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2b240 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2b250 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
2b260 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
2b270 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2b280 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
2b290 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
2b2a0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
2b2b0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2b2c0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
2b2d0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2b2e0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2b2f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2b300 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
2b310 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
2b320 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
2b330 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f  ks.**.** ^To avo
2b340 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
2b350 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
2b360 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
2b370 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
2b380 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
2b390 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
2b3a0 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
2b3b0 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
2b3c0 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
2b3d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
2b3e0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
2b3f0 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
2b400 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  ed collation.** 
2b410 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75  sequence is requ
2b420 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ired..**.** ^If 
2b430 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
2b440 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
2b450 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2b460 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
2b470 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
2b480 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
2b490 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
2b4a0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2b4b0 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
2b4c0 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
2b4d0 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  F-8. ^If sqlite3
2b4e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2b4f0 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
2b500 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
2b510 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
2b520 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
2b530 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
2b540 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  * ^A call to eit
2b550 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
2b560 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69  laces the existi
2b570 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65  ng collation-nee
2b580 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ded callback..**
2b590 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63  .** ^(When the c
2b5a0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
2b5b0 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
2b5c0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
2b5d0 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
2b5e0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2b5f0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
2b600 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
2b610 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2b620 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2b630 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
2b640 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2b650 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2b660 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
2b670 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
2b680 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
2b690 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
2b6a0 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
2b6b0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
2b6c0 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
2b6d0 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
2b6e0 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
2b6f0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
2b700 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
2b710 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
2b720 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2b730 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
2b740 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
2b750 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a   sequence.)^.**.
2b760 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
2b770 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
2b780 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
2b790 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
2b7a0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2b7b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b7c0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
2b7d0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2b7e0 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
2b7f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b800 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ation_v2()]..*/.
2b810 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
2b820 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
2b830 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2b840 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
2b850 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
2b860 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
2b870 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
2b880 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2b890 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
2b8a0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
2b8b0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2b8c0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2b8d0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
2b8e0 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53  d*).);..#ifdef S
2b8f0 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a  QLITE_HAS_CODEC.
2b900 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
2b910 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
2b920 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
2b930 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
2b940 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
2b950 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
2b960 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
2b970 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
2b980 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
2b990 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
2b9a0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
2b9b0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
2b9c0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
2b9d0 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
2b9e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2b9f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2ba00 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
2ba10 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
2ba20 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
2ba30 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
2ba40 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
2ba50 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
2ba60 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
2ba70 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
2ba80 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
2ba90 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
2baa0 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
2bab0 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
2bac0 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
2bad0 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
2bae0 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
2baf0 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
2bb00 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2bb10 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2bb20 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2bb30 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2bb40 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2bb50 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2bb60 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
2bb70 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2bb80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2bb90 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
2bba0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
2bbb0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
2bbc0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
2bbd0 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  new key */.);../
2bbe0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
2bbf0 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
2bc00 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61  for a SEE databa
2bc10 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20  se.  Unless .** 
2bc20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20  activated, none 
2bc30 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69  of the SEE routi
2bc40 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
2bc50 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
2bc60 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63  ctivate_see(.  c
2bc70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
2bc80 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
2bc90 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
2bca0 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
2bcb0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45  .#ifdef SQLITE_E
2bcc0 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a  NABLE_CEROD./*.*
2bcd0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
2bce0 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
2bcf0 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73   a CEROD databas
2bd00 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
2bd10 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
2bd20 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74  f the CEROD rout
2bd30 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
2bd40 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2bd50 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a  activate_cerod(.
2bd60 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
2bd70 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
2bd80 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
2bd90 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
2bda0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2bdb0 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63  EF: Suspend Exec
2bdc0 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
2bdd0 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  t Time.**.** ^Th
2bde0 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
2bdf0 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
2be00 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
2be10 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
2be20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
2be30 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
2be40 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
2be50 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
2be60 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
2be70 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 65  *.** ^If the ope
2be80 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
2be90 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
2bea0 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
2beb0 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
2bec0 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
2bed0 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
2bee0 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
2bef0 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
2bf00 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 5e 54  arest second. ^T
2bf10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
2bf20 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
2bf30 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
2bf40 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
2bf50 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
2bf60 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
2bf70 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d  **.** ^SQLite im
2bf80 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
2bf90 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
2bfa0 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
2bfb0 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
2bfc0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
2bfd0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
2bfe0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
2bff0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
2c000 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2c010 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
2c020 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
2c030 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  Files.**.** ^(If
2c040 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
2c050 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
2c060 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
2c070 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
2c080 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
2c090 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65  der (a.k.a. dire
2c0a0 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c  ctory), then all
2c0b0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
2c0c0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53  .** created by S
2c0d0 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67  QLite when using
2c0e0 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c   a built-in [sql
2c0f0 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a  ite3_vfs | VFS].
2c100 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  ** will be place
2c110 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
2c120 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73  ory.)^  ^If this
2c130 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20   variable.** is 
2c140 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
2c150 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66  then SQLite perf
2c160 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f  orms a search fo
2c170 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
2c180 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
2c190 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
2c1a0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
2c1b0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
2c1c0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
2c1d0 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
2c1e0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
2c1f0 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
2c200 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
2c210 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
2c220 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
2c230 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2c240 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
2c250 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
2c260 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
2c270 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
2c280 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
2c290 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
2c2a0 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
2c2b0 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
2c2c0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
2c2d0 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
2c2e0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
2c2f0 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
2c300 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2c310 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
2c320 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
2c330 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
2c340 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
2c350 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  The [temp_store_
2c360 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2c370 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
2c380 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
2c390 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
2c3a0 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
2c3b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2c3c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
2c3d0 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
2c3e0 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2c3f0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2c400 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
2c410 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
2c420 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
2c430 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
2c440 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
2c450 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2c460 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
2c470 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
2c480 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
2c490 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
2c4a0 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
2c4b0 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
2c4c0 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
2c4d0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
2c4e0 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
2c4f0 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
2c500 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
2c510 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
2c520 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
2c530 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2c540 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
2c550 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
2c560 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2c570 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2c580 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
2c590 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
2c5a0 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
2c5b0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
2c5c0 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
2c5d0 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
2c5e0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
2c5f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
2c600 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
2c610 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c620 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2c630 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2c640 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
2c650 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
2c660 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
2c670 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
2c680 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
2c690 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
2c6a0 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74  pectively.  ^Aut
2c6b0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2c6c0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
2c6d0 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
2c6e0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
2c6f0 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
2c700 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  ement..** ^Autoc
2c710 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
2c720 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
2c730 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
2c740 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
2c750 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
2c760 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
2c770 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
2c780 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
2c790 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
2c7a0 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
2c7b0 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
2c7c0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
2c7d0 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
2c7e0 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
2c7f0 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
2c800 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
2c810 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
2c820 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
2c830 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
2c840 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
2c850 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
2c860 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
2c870 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
2c880 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2c890 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2c8a0 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
2c8b0 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
2c8c0 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
2c8d0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
2c8e0 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
2c8f0 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
2c900 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
2c910 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2c920 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
2c930 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
2c940 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
2c950 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  alue.** is undef
2c960 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
2c970 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2c980 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
2c990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c9a0 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
2c9b0 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
2c9c0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2c9d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c9e0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
2c9f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2ca00 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2ca10 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
2ca20 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
2ca30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ca40 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
2ca50 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2ca60 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
2ca70 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2ca80 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
2ca90 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2caa0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
2cab0 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
2cac0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
2cad0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
2cae0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
2caf0 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
2cb00 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
2cb10 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
2cb20 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
2cb30 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
2cb40 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2cb50 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
2cb60 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2cb70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2cb80 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
2cb90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2cba0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
2cbb0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2cbc0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
2cbd0 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
2cbe0 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a  atement] after.*
2cbf0 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74  * pStmt associat
2cc00 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
2cc10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cc20 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d  ] pDb.  ^If pStm
2cc30 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
2cc40 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
2cc50 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2cc60 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
2cc70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cc80 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
2cc90 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
2cca0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
2ccb0 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61  b.  ^If no prepa
2ccc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2ccd0 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
2cce0 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
2ccf0 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65  s routine, it re
2cd00 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  turns NULL..**.*
2cd10 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20  * The [database 
2cd20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e  connection] poin
2cd30 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20  ter D in a call 
2cd40 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e  to.** [sqlite3_n
2cd50 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d  ext_stmt(D,S)] m
2cd60 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20  ust refer to an 
2cd70 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  open database.**
2cd80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
2cd90 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75  in particular mu
2cda0 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c  st not be a NULL
2cdb0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c   pointer..*/.sql
2cdc0 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
2cdd0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
2cde0 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
2cdf0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2ce00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ce10 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
2ce20 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
2ce30 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
2ce40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ce50 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e  commit_hook() in
2ce60 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2ce70 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
2ce80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
2ce90 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2cea0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2ceb0 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69   [COMMIT | commi
2cec0 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  tted]..** ^Any c
2ced0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2cee0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2cef0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
2cf00 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
2cf10 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2cf20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2cf30 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
2cf40 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
2cf50 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
2cf60 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2cf70 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
2cf80 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
2cf90 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
2cfa0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52  ransaction is [R
2cfb0 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64  OLLBACK | rolled
2cfc0 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20   back]..** ^Any 
2cfd0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
2cfe0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
2cff0 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  to sqlite3_rollb
2d000 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  ack_hook().** fo
2d010 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
2d020 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2d030 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
2d040 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d   ^The pArg argum
2d050 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
2d060 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c  rough to the cal
2d070 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68  lback..** ^If th
2d080 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
2d090 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
2d0a0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
2d0b0 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
2d0c0 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
2d0d0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
2d0e0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
2d0f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
2d100 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e  t_hook(D,C,P) an
2d110 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  d sqlite3_rollba
2d120 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  ck_hook(D,C,P) f
2d130 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75  unctions.** retu
2d140 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  rn the P argumen
2d150 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
2d160 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20  ous call of the 
2d170 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
2d180 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
2d190 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d1a0 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
2d1b0 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
2d1c0 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e  all for each fun
2d1d0 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a  ction on D..**.*
2d1e0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  * The callback i
2d1f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2d200 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2d210 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2d220 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2d230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2d240 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2d250 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61  callback.  Any a
2d260 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
2d270 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2d280 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2d290 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
2d2a0 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
2d2b0 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
2d2c0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2d2d0 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
2d2e0 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69  ggered the commi
2d2f0 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  t.** or rollback
2d300 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72   hook in the fir
2d310 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74  st place..** Not
2d320 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
2d330 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2d340 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
2d350 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
2d360 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
2d370 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
2d380 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
2d390 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
2d3a0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
2d3b0 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61  * ^Registering a
2d3c0 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
2d3d0 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
2d3e0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  back..**.** ^Whe
2d3f0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
2d400 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  k callback routi
2d410 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ne returns zero,
2d420 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a   the [COMMIT].**
2d430 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c   operation is al
2d440 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75  lowed to continu
2d450 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66  e normally.  ^If
2d460 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
2d470 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
2d480 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
2d490 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
2d4a0 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
2d4b0 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20  LBACK]..** ^The 
2d4c0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73  rollback hook is
2d4d0 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f   invoked on a ro
2d4e0 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75  llback that resu
2d4f0 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69  lts from a commi
2d500 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e  t.** hook return
2d510 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75  ing non-zero, ju
2d520 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62  st as it would b
2d530 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72  e with any other
2d540 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
2d550 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
2d560 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
2d570 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2d580 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
2d590 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
2d5a0 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
2d5b0 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
2d5c0 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
2d5d0 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
2d5e0 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
2d5f0 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
2d600 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
2d610 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ccur..** ^The ro
2d620 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
2d630 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
2d640 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
2d650 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
2d660 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
2d670 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
2d680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d690 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
2d6a0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2d6b0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2d6c0 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
2d6d0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2d6e0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
2d6f0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
2d700 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
2d710 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
2d720 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
2d730 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
2d740 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
2d750 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2d760 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
2d770 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
2d780 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2d790 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2d7a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
2d7b0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
2d7c0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  k function.** wi
2d7d0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
2d7e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65   connection] ide
2d7f0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ntified by the f
2d800 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
2d810 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2d820 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
2d830 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
2d840 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
2d850 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
2d860 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2d870 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
2d880 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
2d890 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2d8a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2d8b0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
2d8c0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
2d8d0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2d8e0 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
2d8f0 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
2d900 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70  n a.** row is up
2d910 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
2d920 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
2d930 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2d940 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
2d950 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
2d960 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
2d970 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
2d980 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
2d990 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63  ** ^The second c
2d9a0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
2d9b0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2d9c0 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
2d9d0 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20  ITE_DELETE],.** 
2d9e0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
2d9f0 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  E], depending on
2da00 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
2da10 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
2da20 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65  allback.** to be
2da30 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
2da40 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
2da50 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
2da60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
2da70 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f  tain pointers to
2da80 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2da90 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20   and table name 
2daa0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
2dab0 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20  ffected row..** 
2dac0 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62  ^The final callb
2dad0 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
2dae0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
2daf0 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20  the row..** ^In 
2db00 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
2db10 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
2db20 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72  he [rowid] after
2db30 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
2db40 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  s place..**.** ^
2db50 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b  (The update hook
2db60 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2db70 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
2db80 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a  stem tables are.
2db90 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65  ** modified (i.e
2dba0 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  . sqlite_master 
2dbb0 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
2dbc0 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  nce).)^.**.** ^I
2dbd0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  n the current im
2dbe0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
2dbf0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
2dc00 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2dc10 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e  when duplication
2dc20 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
2dc30 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a  d because of an.
2dc40 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  ** [ON CONFLICT 
2dc50 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45  | ON CONFLICT RE
2dc60 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20  PLACE] clause.  
2dc70 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61  ^Nor is the upda
2dc80 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b  te hook.** invok
2dc90 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65  ed when rows are
2dca0 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74   deleted using t
2dcb0 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  he [truncate opt
2dcc0 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  imization]..** T
2dcd0 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65  he exceptions de
2dce0 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61  fined in this pa
2dcf0 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68  ragraph might ch
2dd00 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
2dd10 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
2dd20 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
2dd30 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70   update hook imp
2dd40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2dd50 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
2dd60 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
2dd70 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
2dd80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
2dd90 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70  t invoked the up
2dda0 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20  date hook.  Any 
2ddb0 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
2ddc0 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
2ddd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2dde0 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
2ddf0 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
2de00 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
2de10 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
2de20 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
2de30 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61  iggered the upda
2de40 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65  te hook..** Note
2de50 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
2de60 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2de70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2de80 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
2de90 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
2dea0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
2deb0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
2dec0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
2ded0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
2dee0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70   ^The sqlite3_up
2def0 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  date_hook(D,C,P)
2df00 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74   function.** ret
2df10 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d  urns the P argum
2df20 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
2df30 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e  vious call.** on
2df40 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
2df50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2df60 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
2df70 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
2df80 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   on D..**.** See
2df90 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
2dfa0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2dfb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2dfc0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a  ollback_hook()].
2dfd0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  ** interfaces..*
2dfe0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
2dff0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
2e000 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2e010 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
2e020 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
2e030 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
2e040 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
2e050 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
2e060 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
2e070 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50  Disable Shared P
2e080 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45  ager Cache.** KE
2e090 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20  YWORDS: {shared 
2e0a0 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54  cache}.**.** ^(T
2e0b0 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
2e0c0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
2e0d0 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
2e0e0 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
2e0f0 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
2e100 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
2e110 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73  between [databas
2e120 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63  e connection | c
2e130 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74  onnections].** t
2e140 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
2e150 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20  ase. Sharing is 
2e160 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
2e170 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a  rgument is true.
2e180 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ** and disabled 
2e190 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
2e1a0 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a  is false.)^.**.*
2e1b0 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67  * ^Cache sharing
2e1c0 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
2e1d0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
2e1e0 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
2e1f0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
2e200 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
2e210 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
2e220 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
2e230 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
2e240 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
2e250 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
2e260 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
2e270 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2e280 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68  * ^(The cache sh
2e290 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
2e2a0 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
2e2b0 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
2e2c0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
2e2d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
2e2e0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2e2f0 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
2e300 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2e310 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
2e320 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e330 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
2e340 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
2e350 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e  e.** that was in
2e360 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
2e370 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
2e380 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  ened.)^.**.** ^(
2e390 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
2e3a0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
2e3b0 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
2e3c0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
2e3d0 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63  disabled.** succ
2e3e0 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
2e3f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2e400 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
2e410 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65  .)^.**.** ^Share
2e420 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
2e430 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
2e440 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
2e450 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
2e460 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2e470 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
2e480 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
2e490 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
2e4a0 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
2e4b0 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
2e4c0 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  citly..**.** See
2e4d0 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20   Also:  [SQLite 
2e4e0 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64  Shared-Cache Mod
2e4f0 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e].*/.int sqlite
2e500 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
2e510 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
2e520 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74  ** CAPI3REF: Att
2e530 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
2e540 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e  p Memory.**.** ^
2e550 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
2e560 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74  ase_memory() int
2e570 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2e580 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a  to free N bytes.
2e590 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  ** of heap memor
2e5a0 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
2e5b0 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  g non-essential 
2e5c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2e5d0 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68  ns.** held by th
2e5e0 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
2e5f0 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65  ry.   Memory use
2e600 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62  d to cache datab
2e610 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20  ase.** pages to 
2e620 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
2e630 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  nce is an exampl
2e640 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  e of non-essenti
2e650 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73  al memory..** ^s
2e660 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2e670 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20  emory() returns 
2e680 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2e690 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
2e6a0 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67  ed,.** which mig
2e6b0 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
2e6c0 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ss than the amou
2e6d0 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f  nt requested..*/
2e6e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
2e6f0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
2e700 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e710 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  F: Impose A Limi
2e720 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a  t On Heap Size.*
2e730 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2e740 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
2e750 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c  t() interface pl
2e760 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69  aces a "soft" li
2e770 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d  mit.** on the am
2e780 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
2e790 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
2e7a0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
2e7b0 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 69  ite..** ^If an i
2e7c0 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69  nternal allocati
2e7d0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20  on is requested 
2e7e0 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65  that would excee
2e7f0 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65  d the.** soft he
2e800 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74  ap limit, [sqlit
2e810 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2e820 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20  y()] is invoked 
2e830 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  one or.** more t
2e840 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20  imes to free up 
2e850 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72  some space befor
2e860 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  e the allocation
2e870 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a   is performed..*
2e880 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69 74 20  *.** ^The limit 
2e890 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22  is called "soft"
2e8a0 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c   because if [sql
2e8b0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2e8c0 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74  ory()].** cannot
2e8d0 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74   free sufficient
2e8e0 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65   memory to preve
2e8f0 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f  nt the limit fro
2e900 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64  m being exceeded
2e910 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  ,.** the memory 
2e920 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79  is allocated any
2e930 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72  way and the curr
2e940 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  ent operation pr
2e950 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  oceeds..**.** ^A
2e960 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
2e970 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65  o value for N me
2e980 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69  ans that there i
2e990 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c  s no soft heap l
2e9a0 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  imit and.** [sql
2e9b0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2e9c0 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79  ory()] will only
2e9d0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2e9e0 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73  memory is exhaus
2e9f0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ted..** ^The def
2ea00 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
2ea10 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2ea20 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  it is zero..**.*
2ea30 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b 65 73  * ^(SQLite makes
2ea40 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74   a best effort t
2ea50 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74  o honor the soft
2ea60 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20   heap limit..** 
2ea70 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20  But if the soft 
2ea80 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f  heap limit canno
2ea90 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78  t be honored, ex
2eaa0 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20  ecution will.** 
2eab0 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74  continue without
2eac0 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69   error or notifi
2ead0 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69 73 20  cation.)^  This 
2eae0 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74  is why the limit
2eaf0 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20   is.** called a 
2eb00 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49  "soft" limit.  I
2eb10 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e  t is advisory on
2eb20 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ly..**.** Prior 
2eb30 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
2eb40 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f  n 3.5.0, this ro
2eb50 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74  utine only const
2eb60 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72  rained the memor
2eb70 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62  y.** allocated b
2eb80 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
2eb90 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72  d - the same thr
2eba0 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69  ead in which thi
2ebb0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e  s routine.** run
2ebc0 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69  s.  Beginning wi
2ebd0 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  th SQLite versio
2ebe0 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66  n 3.5.0, the sof
2ebf0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a  t heap limit is.
2ec00 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c  ** applied to al
2ec10 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76  l threads. The v
2ec20 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66  alue specified f
2ec30 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2ec40 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20   limit.** is an 
2ec50 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74  upper bound on t
2ec60 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20  he total memory 
2ec70 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61  allocation for a
2ec80 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a  ll threads. In.*
2ec90 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  * version 3.5.0 
2eca0 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68  there is no mech
2ecb0 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69  anism for limiti
2ecc0 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67  ng the heap usag
2ecd0 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64  e for.** individ
2ece0 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  ual threads..*/.
2ecf0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
2ed00 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
2ed10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ed20 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61  EF: Extract Meta
2ed30 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
2ed40 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a  umn Of A Table.*
2ed50 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2ed60 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64  ne returns metad
2ed70 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
2ed80 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
2ed90 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74   specific.** dat
2eda0 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65  abase table acce
2edb0 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
2edc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2edd0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
2ede0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2edf0 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72  irst function ar
2ee00 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2ee10 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
2ee20 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
2ee30 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
2ee40 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2ee50 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75  rs to.** this fu
2ee60 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63  nction. ^The sec
2ee70 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2ee80 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65   either the name
2ee90 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2eea0 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22  .** (i.e. "main"
2eeb0 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20  , "temp", or an 
2eec0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2eed0 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
2eee0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
2eef0 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49  able or NULL. ^I
2ef00 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
2ef10 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
2ef20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
2ef30 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
2ef40 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
2ef50 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
2ef60 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74   used by the dat
2ef70 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a  abase engine to.
2ef80 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
2ef90 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
2efa0 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  erences..**.** ^
2efb0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2efc0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
2efd0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2efe0 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
2eff0 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d  nd column.** nam
2f000 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
2f010 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
2f020 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
2f030 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
2f040 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rs.** may be NUL
2f050 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61  L..**.** ^Metada
2f060 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ta is returned b
2f070 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65  y writing to the
2f080 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e   memory location
2f090 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
2f0a0 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65  5th.** and subse
2f0b0 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
2f0c0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
2f0d0 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65  n. ^Any of these
2f0e0 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62   arguments may b
2f0f0 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68  e.** NULL, in wh
2f100 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72  ich case the cor
2f110 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65  responding eleme
2f120 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69  nt of metadata i
2f130 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a  s omitted..**.**
2f140 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a   ^(<blockquote>.
2f150 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2f160 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2f170 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e  > Parameter <th>
2f180 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20   Output<br>Type 
2f190 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f  <th>  Descriptio
2f1a0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2f1b0 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   5th <td> const 
2f1c0 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20  char* <td> Data 
2f1d0 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  type.** <tr><td>
2f1e0 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   6th <td> const 
2f1f0 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20  char* <td> Name 
2f200 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  of default colla
2f210 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a  tion sequence.**
2f220 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74   <tr><td> 7th <t
2f230 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
2f240 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
2f250 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
2f260 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
2f270 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64  <tr><td> 8th <td
2f280 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2f290 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2f2a0 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
2f2b0 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
2f2c0 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64  <tr><td> 9th <td
2f2d0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2f2e0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2f2f0 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d  n is [AUTOINCREM
2f300 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ENT].** </table>
2f310 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2f320 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  >)^.**.** ^The m
2f330 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f  emory pointed to
2f340 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65   by the characte
2f350 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  r pointers retur
2f360 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64  ned for the.** d
2f370 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20  eclaration type 
2f380 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  and collation se
2f390 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20  quence is valid 
2f3a0 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e  only until the n
2f3b0 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61  ext.** call to a
2f3c0 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75  ny SQLite API fu
2f3d0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nction..**.** ^I
2f3e0 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
2f3f0 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c  table is actuall
2f400 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72  y a view, an [er
2f410 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
2f420 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  urned..**.** ^If
2f430 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
2f440 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22  olumn is "rowid"
2f450 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77  , "oid" or "_row
2f460 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b  id_" and an.** [
2f470 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
2f480 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20  KEY] column has 
2f490 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
2f4a0 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
2f4b0 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
2f4c0 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
2f4d0 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74  for the explicit
2f4e0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
2f4f0 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69  mn. ^(If there i
2f500 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74  s no.** explicit
2f510 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54  ly declared [INT
2f520 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
2f530 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  ] column, then t
2f540 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
2f550 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
2f560 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
2f570 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
2f580 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
2f590 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
2f5a0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
2f5b0 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
2f5c0 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
2f5d0 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
2f5e0 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
2f5f0 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
2f600 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  re>)^.**.** ^(Th
2f610 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
2f620 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
2f630 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
2f640 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
2f650 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
2f660 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
2f670 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
2f680 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
2f690 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
2f6a0 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
2f6b0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
2f6c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
2f6d0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
2f6e0 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65  e left.** in the
2f6f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f700 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65  ction] (to be re
2f710 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
2f720 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
2f730 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41  )^.**.** ^This A
2f740 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  PI is only avail
2f750 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
2f760 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
2f770 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
2f780 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
2f790 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
2f7a0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2f7b0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
2f7c0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
2f7d0 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
2f7e0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2f7f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f800 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
2f810 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2f820 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
2f830 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2f840 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
2f850 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2f860 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
2f870 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
2f880 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2f890 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
2f8a0 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
2f8b0 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
2f8c0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
2f8d0 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
2f8e0 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
2f8f0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
2f900 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
2f910 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
2f920 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
2f930 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
2f940 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
2f950 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
2f960 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
2f970 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
2f980 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
2f990 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
2f9a0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
2f9b0 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
2f9c0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
2f9d0 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
2f9e0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
2f9f0 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
2fa00 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
2fa10 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
2fa20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
2fa30 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a  n Extension.**.*
2fa40 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
2fa50 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74  e loads an SQLit
2fa60 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
2fa70 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d  ary from the nam
2fa80 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed file..**.** ^
2fa90 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
2faa0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
2fab0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2fac0 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51  to load an.** SQ
2fad0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
2fae0 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
2faf0 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69   in the file zFi
2fb00 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  le..**.** ^The e
2fb10 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
2fb20 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d  roc..** ^zProc m
2fb30 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63  ay be 0, in whic
2fb40 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
2fb50 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
2fb60 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74  nt.** defaults t
2fb70 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
2fb80 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e  sion_init"..** ^
2fb90 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
2fba0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
2fbb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2fbc0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  * [SQLITE_OK] on
2fbd0 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
2fbe0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
2fbf0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
2fc00 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ong..** ^If an e
2fc10 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
2fc20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
2fc30 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  0, then the.** [
2fc40 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
2fc50 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
2fc60 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70  ace shall attemp
2fc70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a  t to.** fill *pz
2fc80 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f  ErrMsg with erro
2fc90 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
2fca0 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  tored in memory.
2fcb0 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
2fcc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2fcd0 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67  ()]. The calling
2fce0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f   function.** sho
2fcf0 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
2fd00 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20  mory by calling 
2fd10 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2fd20 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69  ..**.** ^Extensi
2fd30 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
2fd40 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
2fd50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  .** [sqlite3_ena
2fd60 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
2fd70 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63  on()] prior to c
2fd80 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c  alling this API,
2fd90 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
2fda0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
2fdb0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
2fdc0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61  ee also the [loa
2fdd0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51  d_extension() SQ
2fde0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a  L function]..*/.
2fdf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
2fe00 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
2fe10 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2fe20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
2fe30 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
2fe40 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
2fe50 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
2fe60 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
2fe70 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
2fe80 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
2fe90 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
2fea0 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
2feb0 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
2fec0 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
2fed0 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
2fee0 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
2fef0 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
2ff00 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
2ff10 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
2ff20 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
2ff30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
2ff40 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
2ff50 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
2ff60 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20  ng.**.** ^So as 
2ff70 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
2ff80 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
2ff90 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
2ffa0 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
2ffb0 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
2ffc0 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
2ffd0 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
2ffe0 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
2fff0 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
30000 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
30010 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
30020 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
30030 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a  following API.**
30040 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
30050 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
30060 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
30070 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
30080 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20   and off..**.** 
30090 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69  ^Extension loadi
300a0 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  ng is off by def
300b0 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74  ault. See ticket
300c0 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c   #1863..** ^Call
300d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61   the sqlite3_ena
300e0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
300f0 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74  on() routine wit
30100 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f  h onoff==1.** to
30110 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
30120 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63  loading on and c
30130 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
30140 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20  f==0 to turn.** 
30150 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
30160 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
30170 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
30180 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
30190 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
301a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
301b0 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  : Automatically 
301c0 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f  Load An Extensio
301d0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41  ns.**.** ^This A
301e0 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65  PI can be invoke
301f0 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61  d at program sta
30200 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f  rtup in order to
30210 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65   register.** one
30220 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61   or more statica
30230 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e  lly linked exten
30240 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20  sions that will 
30250 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  be available.** 
30260 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61  to all new [data
30270 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
30280 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ]..**.** ^(This 
30290 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61  routine stores a
302a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
302b0 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20  extension entry 
302c0 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e 20 61  point.** in an a
302d0 72 72 61 79 20 74 68 61 74 20 69 73 20 6f 62 74  rray that is obt
302e0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
302f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
30300 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  That memory.** i
30310 73 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  s deallocated by
30320 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
30330 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
30340 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ].)^.**.** ^This
30350 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
30360 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e  ers an extension
30370 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61   entry point tha
30380 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  t is.** automati
30390 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68  cally invoked wh
303a0 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61  enever a new [da
303b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
303c0 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65 64 20  n].** is opened 
303d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  using [sqlite3_o
303e0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
303f0 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f  _open16()],.** o
30400 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
30410 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70 6c 69  v2()]..** ^Dupli
30420 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  cate extensions 
30430 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20  are detected so 
30440 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  calling this rou
30450 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  tine.** multiple
30460 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
30470 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69  same extension i
30480 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 20 5e  s harmless..** ^
30490 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  Automatic extens
304a0 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73  ions apply acros
304b0 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a  s all threads..*
304c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75  /.int sqlite3_au
304d0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
304e0 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29  d (*xEntryPoint)
304f0 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void));../*.** 
30500 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
30510 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73  Automatic Extens
30520 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a  ion Loading.**.*
30530 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f  * ^(This functio
30540 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70  n disables all p
30550 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
30560 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a  ered automatic.*
30570 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 49 74  * extensions. It
30580 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
30590 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a  ct of all prior.
305a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f  ** [sqlite3_auto
305b0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61  _extension()] ca
305c0 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lls.)^.**.** ^Th
305d0 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  is function disa
305e0 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65  bles automatic e
305f0 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c  xtensions in all
30600 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69   threads..*/.voi
30610 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f  d sqlite3_reset_
30620 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
30630 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  oid);../*.** The
30640 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
30650 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
30660 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72  mechanism is cur
30670 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
30680 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
30690 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
306a0 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
306b0 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
306c0 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
306d0 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
306e0 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
306f0 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
30700 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
30710 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
30720 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
30730 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
30740 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
30750 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
30760 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
30770 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
30780 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
30790 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
307a0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
307b0 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
307c0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
307d0 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
307e0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
307f0 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
30800 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
30810 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
30820 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
30830 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
30840 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
30850 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
30860 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30870 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
30880 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
30890 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
308a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
308b0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
308c0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
308d0 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64  RDS: sqlite3_mod
308e0 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62  ule {virtual tab
308f0 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a  le module}.**.**
30900 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c   This structure,
30910 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65   sometimes calle
30920 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74  d a a "virtual t
30930 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a  able module", .*
30940 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d  * defines the im
30950 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
30960 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
30970 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74  s].  .** This st
30980 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73  ructure consists
30990 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f   mostly of metho
309a0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
309b0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74  e..**.** ^A virt
309c0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
309d0 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66   is created by f
309e0 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73  illing in a pers
309f0 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e  istent.** instan
30a00 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
30a10 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67  ture and passing
30a20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
30a30 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74  at instance.** t
30a40 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
30a50 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b  e_module()] or [
30a60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
30a70 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  odule_v2()]..** 
30a80 5e 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f  ^The registratio
30a90 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20  n remains valid 
30aa0 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c  until it is repl
30ab0 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72  aced by a differ
30ac0 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72  ent.** module or
30ad0 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61   until the [data
30ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30af0 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f   closes.  The co
30b00 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73  ntent.** of this
30b10 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
30b20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65  not change while
30b30 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65   it is registere
30b40 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61  d with.** any da
30b50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30b60 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  n..*/.struct sql
30b70 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20  ite3_module {.  
30b80 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
30b90 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73  int (*xCreate)(s
30ba0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
30bb0 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
30bc0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
30bd0 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
30be0 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
30bf0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
30c00 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
30c10 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  **);.  int (*xCo
30c20 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c  nnect)(sqlite3*,
30c30 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
30c40 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
30c50 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
30c60 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
30c70 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
30c80 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
30c90 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
30ca0 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29  nt (*xBestIndex)
30cb0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
30cc0 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e  VTab, sqlite3_in
30cd0 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e  dex_info*);.  in
30ce0 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29  t (*xDisconnect)
30cf0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
30d00 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
30d10 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33  Destroy)(sqlite3
30d20 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
30d30 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
30d40 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
30d50 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
30d60 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
30d70 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  r);.  int (*xClo
30d80 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  se)(sqlite3_vtab
30d90 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
30da0 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69   (*xFilter)(sqli
30db0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
30dc0 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f  , int idxNum, co
30dd0 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72  nst char *idxStr
30de0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
30df0 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69    int argc, sqli
30e00 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76  te3_value **argv
30e10 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74  );.  int (*xNext
30e20 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
30e30 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
30e40 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76  *xEof)(sqlite3_v
30e50 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
30e60 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73  int (*xColumn)(s
30e70 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30e80 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  or*, sqlite3_con
30e90 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  text*, int);.  i
30ea0 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c  nt (*xRowid)(sql
30eb0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
30ec0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
30ed0 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74   *pRowid);.  int
30ee0 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69   (*xUpdate)(sqli
30ef0 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c  te3_vtab *, int,
30f00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
30f10 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
30f20 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65   *);.  int (*xBe
30f30 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  gin)(sqlite3_vta
30f40 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
30f50 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
30f60 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
30f70 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29    int (*xCommit)
30f80 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
30f90 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
30fa0 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
30fb0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
30fc0 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e    int (*xFindFun
30fd0 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76  ction)(sqlite3_v
30fe0 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20  tab *pVtab, int 
30ff0 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72  nArg, const char
31000 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20   *zName,.       
31010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31020 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28  void (**pxFunc)(
31030 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31040 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31050 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20  ue**),.         
31060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
31070 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69  id **ppArg);.  i
31080 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71  nt (*xRename)(sq
31090 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
310a0 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
310b0 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  New);.};../*.** 
310c0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
310d0 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67  l Table Indexing
310e0 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   Information.** 
310f0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
31100 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a  3_index_info.**.
31110 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
31120 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74  ndex_info struct
31130 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73  ure and its subs
31140 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65  tructures is use
31150 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66  d to.** pass inf
31160 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e  ormation into an
31170 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65  d receive the re
31180 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42  ply from the [xB
31190 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74  estIndex].** met
311a0 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61  hod of a [virtua
311b0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
311c0 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64    The fields und
311d0 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72  er **Inputs** ar
311e0 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20  e the.** inputs 
311f0 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e  to xBestIndex an
31200 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  d are read-only.
31210 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73    xBestIndex ins
31220 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75  erts its.** resu
31230 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f  lts into the **O
31240 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e  utputs** fields.
31250 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f  .**.** ^(The aCo
31260 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
31270 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63   records WHERE c
31280 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
31290 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a  s of the form:.*
312a0 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e  *.** <pre>column
312b0 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a   OP expr</pre>.*
312c0 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73  *.** where OP is
312d0 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c   =, &lt;, &lt;=,
312e0 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e   &gt;, or &gt;=.
312f0 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63  )^  ^(The partic
31300 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73  ular operator is
31310 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43  .** stored in aC
31320 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 29  onstraint[].op.)
31330 5e 20 20 5e 28 54 68 65 20 69 6e 64 65 78 20 6f  ^  ^(The index o
31340 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
31350 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f  stored in.** aCo
31360 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75  nstraint[].iColu
31370 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72  mn.)^  ^(aConstr
31380 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
31390 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
313a0 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
313b0 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
313c0 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
313d0 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
313e0 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
313f0 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
31400 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a   it cannot.)^.**
31410 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a  .** ^The optimiz
31420 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  er automatically
31430 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f   inverts terms o
31440 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72  f the form "expr
31450 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61   OP column".** a
31460 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73  nd makes other s
31470 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74  implifications t
31480 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75  o the WHERE clau
31490 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74  se in an attempt
314a0 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61   to.** get as ma
314b0 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ny WHERE clause 
314c0 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66  terms into the f
314d0 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  orm shown above 
314e0 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20  as possible..** 
314f0 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74  ^The aConstraint
31500 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65  [] array only re
31510 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75  ports WHERE clau
31520 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 61 72  se terms that ar
31530 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f  e.** relevant to
31540 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
31550 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65  virtual table be
31560 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a  ing queried..**.
31570 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20  ** ^Information 
31580 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20  about the ORDER 
31590 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f  BY clause is sto
315a0 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b  red in aOrderBy[
315b0 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d  ]..** ^Each term
315c0 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63   of aOrderBy rec
315d0 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66  ords a column of
315e0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
315f0 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ause..**.** The 
31600 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74  [xBestIndex] met
31610 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43  hod must fill aC
31620 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
31630 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f   with informatio
31640 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20  n.** about what 
31650 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61  parameters to pa
31660 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20  ss to xFilter.  
31670 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20  ^If argvIndex>0 
31680 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68  then.** the righ
31690 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74  t-hand side of t
316a0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
316b0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69   aConstraint[] i
316c0 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61  s evaluated.** a
316d0 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61  nd becomes the a
316e0 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72  rgvIndex-th entr
316f0 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66  y in argv.  ^(If
31700 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
31710 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74  e[].omit.** is t
31720 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f  rue, then the co
31730 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75  nstraint is assu
31740 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20  med to be fully 
31750 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a  handled by the.*
31760 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * virtual table 
31770 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b  and is not check
31780 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69  ed again by SQLi
31790 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te.)^.**.** ^The
317a0 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50   idxNum and idxP
317b0 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65  tr values are re
317c0 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65  corded and passe
317d0 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78  d into the.** [x
317e0 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a  Filter] method..
317f0 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65  ** ^[sqlite3_fre
31800 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  e()] is used to 
31810 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61  free idxPtr if a
31820 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65  nd only if.** ne
31830 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69  edToFreeIdxPtr i
31840 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s true..**.** ^T
31850 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  he orderByConsum
31860 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75  ed means that ou
31870 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74  tput from [xFilt
31880 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c  er]/[xNext] will
31890 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65   occur in.** the
318a0 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74   correct order t
318b0 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52  o satisfy the OR
318c0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f  DER BY clause so
318d0 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74   that no separat
318e0 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65  e.** sorting ste
318f0 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  p is required..*
31900 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61  *.** ^The estima
31910 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
31920 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
31930 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
31940 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
31950 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
31960 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
31970 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
31980 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
31990 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
319a0 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
319b0 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
319c0 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
319d0 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
319e0 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
319f0 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
31a00 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
31a10 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
31a20 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
31a30 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
31a40 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
31a50 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
31a60 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
31a70 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
31a80 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
31a90 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
31aa0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
31ab0 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
31ac0 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
31ad0 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
31ae0 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
31af0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
31b00 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
31b10 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
31b20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
31b30 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
31b40 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
31b50 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
31b60 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
31b70 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
31b80 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
31b90 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
31ba0 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
31bb0 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
31bc0 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
31bd0 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
31be0 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
31bf0 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
31c00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
31c10 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
31c20 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
31c30 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
31c40 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
31c50 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
31c60 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
31c70 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
31c80 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
31c90 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
31ca0 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
31cb0 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
31cc0 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
31cd0 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
31ce0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31cf0 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
31d00 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70  use */.  /* Outp
31d10 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  uts */.  struct 
31d20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
31d30 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b  nstraint_usage {
31d40 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64  .    int argvInd
31d50 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ex;           /*
31d60 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69   if >0, constrai
31d70 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72  nt is part of ar
31d80 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f  gv to xFilter */
31d90 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68  .    unsigned ch
31da0 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a  ar omit;      /*
31db0 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74   Do not code a t
31dc0 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e  est for this con
31dd0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a  straint */.  } *
31de0 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
31df0 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20  ;.  int idxNum; 
31e00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
31e10 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f  * Number used to
31e20 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e   identify the in
31e30 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69  dex */.  char *i
31e40 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20  dxStr;          
31e50 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70      /* String, p
31e60 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64  ossibly obtained
31e70 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
31e80 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65  lloc */.  int ne
31e90 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20  edToFreeIdxStr; 
31ea0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78       /* Free idx
31eb0 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65  Str using sqlite
31ec0 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65  3_free() if true
31ed0 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42   */.  int orderB
31ee0 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20  yConsumed;      
31ef0 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70   /* True if outp
31f00 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72  ut is already or
31f10 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c  dered */.  doubl
31f20 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b  e estimatedCost;
31f30 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74        /* Estimat
31f40 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67  ed cost of using
31f50 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d   this index */.}
31f60 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
31f70 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
31f80 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e  T_EQ    2.#defin
31f90 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
31fa0 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20  ONSTRAINT_GT    
31fb0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
31fc0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
31fd0 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e  T_LE    8.#defin
31fe0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
31ff0 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20  ONSTRAINT_LT    
32000 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
32010 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
32020 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66  NT_GE    32.#def
32030 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
32040 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43  _CONSTRAINT_MATC
32050 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  H 64../*.** CAPI
32060 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
32070 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
32080 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
32090 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
320a0 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  nes are used to 
320b0 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b  register a new [
320c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
320d0 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  dule] name..** ^
320e0 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73  Module names mus
320f0 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
32100 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69  before.** creati
32110 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61  ng a new [virtua
32120 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74  l table] using t
32130 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65  he module and be
32140 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20  fore using a.** 
32150 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72  preexisting [vir
32160 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20  tual table] for 
32170 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a  the module..**.*
32180 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61  * ^The module na
32190 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64  me is registered
321a0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
321b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
321c0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
321d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
321e0 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  r.  ^The name of
321f0 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67   the module is g
32200 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20  iven by the .** 
32210 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
32220 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
32230 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
32240 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69  nter to.** the i
32250 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32260 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
32270 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e  ble module].   ^
32280 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61  The fourth.** pa
32290 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
322a0 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64  bitrary client d
322b0 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
322c0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
322d0 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b  gh.** into the [
322e0 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43  xCreate] and [xC
322f0 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20  onnect] methods 
32300 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
32310 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77  able module.** w
32320 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61  hen a new virtua
32330 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 65  l table is be be
32340 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 72  ing created or r
32350 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a  einitialized..**
32360 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32370 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
32380 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 68 61  2() interface ha
32390 73 20 61 20 66 69 66 74 68 20 70 61 72 61 6d 65  s a fifth parame
323a0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
323b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64  a pointer to a d
323c0 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
323d0 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20  e pClientData.  
323e0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20  ^SQLite will.** 
323f0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
32400 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28  uctor function (
32410 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  if it is not NUL
32420 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a  L) when SQLite.*
32430 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  * no longer need
32440 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  s the pClientDat
32450 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  a pointer.  ^The
32460 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32470 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65  module().** inte
32480 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c  rface is equival
32490 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
324a0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
324b0 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a  ) with a NULL.**
324c0 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a   destructor..*/.
324d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
324e0 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c  te_module(.  sql
324f0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
32500 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
32510 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
32520 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
32530 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
32540 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
32550 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
32560 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
32570 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
32580 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65  dule *p,   /* Me
32590 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
325a0 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
325b0 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20  pClientData     
325c0 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
325d0 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
325e0 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69  xConnect */.);.i
325f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
32600 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73  e_module_v2(.  s
32610 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
32620 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
32630 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
32640 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
32650 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
32660 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
32670 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
32680 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
32690 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
326a0 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
326b0 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
326c0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
326d0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20   *pClientData,  
326e0 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
326f0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
32700 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20  e/xConnect */.  
32710 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
32720 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f  void*)     /* Mo
32730 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20  dule destructor 
32740 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a  function */.);..
32750 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32760 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e  Virtual Table In
32770 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  stance Object.**
32780 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
32790 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76  e3_vtab.**.** Ev
327a0 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62  ery [virtual tab
327b0 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65  le module] imple
327c0 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
327d0 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20   subclass.** of 
327e0 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20 64  this object to d
327f0 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63  escribe a partic
32800 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a  ular instance.**
32810 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
32820 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73   table].  Each s
32830 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20  ubclass will.** 
32840 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74  be tailored to t
32850 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
32860 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  s of the module 
32870 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
32880 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f  ** The purpose o
32890 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73  f this superclas
328a0 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63  s is to define c
328b0 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68  ertain fields th
328c0 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e  at are.** common
328d0 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69   to all module i
328e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
328f0 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74  **.** ^Virtual t
32900 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61  ables methods ca
32910 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d  n set an error m
32920 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e  essage by assign
32930 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20  ing a.** string 
32940 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
32950 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
32960 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54  ] to zErrMsg.  T
32970 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  he method should
32980 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68  .** take care th
32990 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72  at any prior str
329a0 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20  ing is freed by 
329b0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
329c0 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72  e3_free()].** pr
329d0 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67  ior to assigning
329e0 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f   a new string to
329f0 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74 65   zErrMsg.  ^Afte
32a00 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
32a10 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65  age.** is delive
32a20 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c  red up to the cl
32a30 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ient application
32a40 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  , the string wil
32a50 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
32a60 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73  ly.** freed by s
32a70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e  qlite3_free() an
32a80 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69  d the zErrMsg fi
32a90 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f  eld will be zero
32aa0 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ed..*/.struct sq
32ab0 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
32ac0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
32ad0 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
32ae0 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
32af0 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
32b00 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
32b10 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
32b20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c           /* NO L
32b30 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20 20  ONGER USED */.  
32b40 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20  char *zErrMsg;  
32b50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32b60 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65  /* Error message
32b70 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70   from sqlite3_mp
32b80 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20  rintf() */.  /* 
32b90 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
32ba0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
32bb0 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
32bc0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
32bd0 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ds */.};../*.** 
32be0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
32bf0 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f  l Table Cursor O
32c00 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
32c10 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  S: sqlite3_vtab_
32c20 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20  cursor {virtual 
32c30 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a  table cursor}.**
32c40 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75  .** Every [virtu
32c50 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
32c60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32c70 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
32c80 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  of the.** follow
32c90 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f  ing structure to
32ca0 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72   describe cursor
32cb0 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74  s that point int
32cc0 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61  o the.** [virtua
32cd0 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65  l table] and are
32ce0 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70   used.** to loop
32cf0 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72   through the vir
32d00 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72  tual table.  Cur
32d10 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64  sors are created
32d20 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
32d30 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f  qlite3_module.xO
32d40 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74  pen | xOpen] met
32d50 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  hod of the modul
32d60 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f  e and are destro
32d70 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73  yed.** by the [s
32d80 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43  qlite3_module.xC
32d90 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d  lose | xClose] m
32da0 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73 20  ethod.  Cursors 
32db0 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74  are used.** by t
32dc0 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78  he [xFilter], [x
32dd0 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b  Next], [xEof], [
32de0 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78  xColumn], and [x
32df0 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a  Rowid] methods.*
32e00 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  * of the module.
32e10 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d    Each module im
32e20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
32e30 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  l define.** the 
32e40 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72  content of a cur
32e50 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f  sor structure to
32e60 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65   suit its own ne
32e70 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eds..**.** This 
32e80 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74  superclass exist
32e90 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65  s in order to de
32ea0 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74  fine fields of t
32eb0 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a  he cursor that.*
32ec0 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20  * are common to 
32ed0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  all implementati
32ee0 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ons..*/.struct s
32ef0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
32f00 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76  or {.  sqlite3_v
32f10 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20  tab *pVtab;     
32f20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
32f30 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72  e of this cursor
32f40 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
32f50 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
32f60 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
32f70 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
32f80 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
32f90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32fa0 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53  F: Declare The S
32fb0 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75  chema Of A Virtu
32fc0 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e  al Table.**.** ^
32fd0 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  The [xCreate] an
32fe0 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
32ff0 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69  hods of a.** [vi
33000 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
33010 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e  le] call this in
33020 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65  terface.** to de
33030 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74  clare the format
33040 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20   (the names and 
33050 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65  datatypes of the
33060 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20   columns) of.** 
33070 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
33080 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e  es they implemen
33090 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
330a0 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73  3_declare_vtab(s
330b0 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
330c0 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a  har *zSQL);../*.
330d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65  ** CAPI3REF: Ove
330e0 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e  rload A Function
330f0 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54   For A Virtual T
33100 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72  able.**.** ^(Vir
33110 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20  tual tables can 
33120 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74  provide alternat
33130 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
33140 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ons of functions
33150 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78  .** using the [x
33160 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65  FindFunction] me
33170 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72  thod of the [vir
33180 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
33190 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f  e].  .** But glo
331a0 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  bal versions of 
331b0 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a  those functions.
331c0 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e  ** must exist in
331d0 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65   order to be ove
331e0 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  rloaded.)^.**.**
331f0 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65   ^(This API make
33200 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20  s sure a global 
33210 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e  version of a fun
33220 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72  ction with a par
33230 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20  ticular.** name 
33240 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  and number of pa
33250 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e  rameters exists.
33260 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e    If no such fun
33270 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20  ction exists.** 
33280 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20  before this API 
33290 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77  is called, a new
332a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65   function is cre
332b0 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d  ated.)^  ^The im
332c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
332d0 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  of the new funct
332e0 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65  ion always cause
332f0 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74  s an exception t
33300 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f  o be thrown.  So
33310 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63  .** the new func
33320 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64  tion is not good
33330 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79   for anything by
33340 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e   itself.  Its on
33350 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73  ly.** purpose is
33360 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f   to be a placeho
33370 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68  lder function th
33380 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f  at can be overlo
33390 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69  aded.** by a [vi
333a0 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f  rtual table]..*/
333b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65  .int sqlite3_ove
333c0 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73  rload_function(s
333d0 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
333e0 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20  har *zFuncName, 
333f0 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a  int nArg);../*.*
33400 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
33410 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
33420 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64  able mechanism d
33430 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61  efined above (ba
33440 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f  ck up.** to a co
33450 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79  mment remarkably
33460 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73   similar to this
33470 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74   one) is current
33480 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
33490 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
334a0 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
334b0 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
334c0 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
334d0 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
334e0 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
334f0 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
33500 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
33510 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
33520 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
33530 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
33540 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
33550 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
33560 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
33570 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
33580 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
33590 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
335a0 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
335b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
335c0 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f  A Handle To An O
335d0 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57  pen BLOB.** KEYW
335e0 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64  ORDS: {BLOB hand
335f0 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65  le} {BLOB handle
33600 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
33610 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
33620 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
33630 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77  n open BLOB on w
33640 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
33650 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
33660 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
33670 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  O] can be perfor
33680 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73  med..** ^Objects
33690 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72   of this type ar
336a0 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71  e created by [sq
336b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
336c0 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f  )].** and destro
336d0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
336e0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
336f0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
33700 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64  blob_read()] and
33710 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
33720 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63  rite()] interfac
33730 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  es.** can be use
33740 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69  d to read or wri
33750 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74  te small subsect
33760 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ions of the BLOB
33770 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
33780 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
33790 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
337a0 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
337b0 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73  he BLOB in bytes
337c0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
337d0 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  uct sqlite3_blob
337e0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a   sqlite3_blob;..
337f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33800 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20  Open A BLOB For 
33810 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a  Incremental I/O.
33820 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
33830 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20  erfaces opens a 
33840 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68  [BLOB handle | h
33850 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c  andle] to the BL
33860 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e  OB located.** in
33870 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d   row iRow, colum
33880 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65  n zColumn, table
33890 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62   zTable in datab
338a0 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f  ase zDb;.** in o
338b0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
338c0 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77  same BLOB that w
338d0 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64  ould be selected
338e0 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e   by:.**.** <pre>
338f0 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a  .**     SELECT z
33900 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e  Column FROM zDb.
33910 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f  zTable WHERE [ro
33920 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20  wid] = iRow;.** 
33930 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  </pre>)^.**.** ^
33940 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  If the flags par
33950 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65  ameter is non-ze
33960 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f  ro, then the BLO
33970 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
33980 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74  read.** and writ
33990 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74  e access. ^If it
339a0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c   is zero, the BL
339b0 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  OB is opened for
339c0 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a   read access..**
339d0 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73   ^It is not poss
339e0 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63  ible to open a c
339f0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61  olumn that is pa
33a00 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f  rt of an index o
33a10 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65  r primary .** ke
33a20 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e  y for writing. ^
33a30 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  If [foreign key 
33a40 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65  constraints] are
33a50 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20   enabled, it is 
33a60 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
33a70 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d   to open a colum
33a80 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f  n that is part o
33a90 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20  f a [child key] 
33aa0 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a  for writing..**.
33ab0 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
33ac0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
33ad0 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e  is not the filen
33ae0 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ame that contain
33af0 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  s.** the databas
33b00 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65  e but rather the
33b10 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f   symbolic name o
33b20 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  f the database t
33b30 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61  hat.** appears a
33b40 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77  fter the AS keyw
33b50 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ord when the dat
33b60 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74  abase is connect
33b70 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48  ed using [ATTACH
33b80 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d  ]..** ^For the m
33b90 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
33ba0 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  e, the database 
33bb0 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a  name is "main"..
33bc0 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62  ** ^For TEMP tab
33bd0 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73  les, the databas
33be0 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22  e name is "temp"
33bf0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63  ..**.** ^(On suc
33c00 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  cess, [SQLITE_OK
33c10 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
33c20 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20  d the new [BLOB 
33c30 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74  handle] is writt
33c40 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62  en.** to *ppBlob
33c50 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  . Otherwise an [
33c60 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
33c70 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42  eturned and *ppB
33c80 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  lob is set.** to
33c90 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74   be a null point
33ca0 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66  er.)^.** ^This f
33cb0 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65  unction sets the
33cc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33cd0 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64  ction] error cod
33ce0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a  e and message.**
33cf0 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
33d00 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
33d10 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33d20 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72  _errmsg()] and r
33d30 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69  elated.** functi
33d40 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20  ons. ^Note that 
33d50 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69  the *ppBlob vari
33d60 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69  able is always i
33d70 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a  nitialized in a.
33d80 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65  ** way that make
33d90 73 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76  s it safe to inv
33da0 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  oke [sqlite3_blo
33db0 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70  b_close()] on *p
33dc0 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c  pBlob.** regardl
33dd0 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
33de0 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ss or failure of
33df0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a   this routine..*
33e00 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f  *.** ^(If the ro
33e10 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61  w that a BLOB ha
33e20 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  ndle points to i
33e30 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e  s modified by an
33e40 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44  .** [UPDATE], [D
33e50 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f  ELETE], or by [O
33e60 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65  N CONFLICT] side
33e70 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e  -effects.** then
33e80 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
33e90 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65   is marked as "e
33ea0 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73  xpired"..** This
33eb0 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20   is true if any 
33ec0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f  column of the ro
33ed0 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76  w is changed, ev
33ee0 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f  en a column.** o
33ef0 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e  ther than the on
33f00 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  e the BLOB handl
33f10 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a  e is open on.)^.
33f20 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71  ** ^Calls to [sq
33f30 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
33f40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
33f50 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f  blob_write()] fo
33f60 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42  r.** a expired B
33f70 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20  LOB handle fail 
33f80 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63  with an return c
33f90 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41  ode of [SQLITE_A
33fa0 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e  BORT]..** ^(Chan
33fb0 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  ges written into
33fc0 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f   a BLOB prior to
33fd0 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69   the BLOB expiri
33fe0 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f  ng are not.** ro
33ff0 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65  lled back by the
34000 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74   expiration of t
34010 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63  he BLOB.  Such c
34020 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e  hanges will even
34030 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74  tually.** commit
34040 20 69 66 20 74 68 65 20 74 72 61 6e 73 61 63 74   if the transact
34050 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ion continues to
34060 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a   completion.)^.*
34070 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b 73  *.** ^Use the [s
34080 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
34090 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  s()] interface t
340a0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
340b0 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  size of.** the o
340c0 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68  pened blob.  ^Th
340d0 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62  e size of a blob
340e0 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e   may not be chan
340f0 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69  ged by this.** i
34100 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65 20 74  nterface.  Use t
34110 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20  he [UPDATE] SQL 
34120 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67  command to chang
34130 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a  e the size of a.
34140 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e  ** blob..**.** ^
34150 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
34160 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e  d_zeroblob()] an
34170 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
34180 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e  t_zeroblob()] in
34190 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20  terfaces.** and 
341a0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65  the built-in [ze
341b0 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63  roblob] SQL func
341c0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
341d0 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a  , if desired,.**
341e0 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d   to create an em
341f0 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64  pty, zero-filled
34200 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74   blob in which t
34210 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  o read or write 
34220 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e  using.** this in
34230 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
34240 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72  o avoid a resour
34250 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f  ce leak, every o
34260 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
34270 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61  ] should eventua
34280 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73  lly.** be releas
34290 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
342a0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
342b0 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ose()]..*/.int s
342c0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
342d0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
342e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c  const char *zDb,
342f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34300 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63  Table,.  const c
34310 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20  har *zColumn,.  
34320 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52  sqlite3_int64 iR
34330 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c  ow,.  int flags,
34340 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  .  sqlite3_blob 
34350 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a  **ppBlob.);../*.
34360 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
34370 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65  se A BLOB Handle
34380 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73 20 61  .**.** ^Closes a
34390 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e  n open [BLOB han
343a0 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f  dle]..**.** ^Clo
343b0 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c  sing a BLOB shal
343c0 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72  l cause the curr
343d0 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ent transaction 
343e0 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20  to commit.** if 
343f0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68  there are no oth
34400 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e  er BLOBs, no pen
34410 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74  ding prepared st
34420 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68  atements, and th
34430 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
34440 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b  nnection is in [
34450 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d  autocommit mode]
34460 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77 72 69  ..** ^If any wri
34470 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f  tes were made to
34480 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20   the BLOB, they 
34490 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e  might be held in
344a0 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20   cache.** until 
344b0 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74  the close operat
344c0 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c  ion if they will
344d0 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c   fit..**.** ^(Cl
344e0 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f  osing the BLOB o
344f0 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20  ften forces the 
34500 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74  changes.** out t
34510 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66  o disk and so if
34520 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20   any I/O errors 
34530 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c  occur, they will
34540 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a   likely occur.**
34550 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
34560 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c  n the BLOB is cl
34570 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72  osed.  Any error
34580 73 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72  s that occur dur
34590 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61  ing.** closing a
345a0 72 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61  re reported as a
345b0 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e   non-zero return
345c0 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20   value.)^.**.** 
345d0 5e 28 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c  ^(The BLOB is cl
345e0 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e  osed uncondition
345f0 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74  ally.  Even if t
34600 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
34610 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  rns.** an error 
34620 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69  code, the BLOB i
34630 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 29  s still closed.)
34640 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ^.**.** ^Calling
34650 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
34660 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65  th a null pointe
34670 72 20 28 73 75 63 68 20 61 73 20 77 6f 75 6c 64  r (such as would
34680 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   be returned.** 
34690 62 79 20 61 20 66 61 69 6c 65 64 20 63 61 6c 6c  by a failed call
346a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
346b0 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20  b_open()]) is a 
346c0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
346d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
346e0 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  lob_close(sqlite
346f0 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a  3_blob *);../*.*
34700 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75  * CAPI3REF: Retu
34710 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41  rn The Size Of A
34720 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a  n Open BLOB.**.*
34730 2a 20 5e 52 65 74 75 72 6e 73 20 74 68 65 20 73  * ^Returns the s
34740 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20  ize in bytes of 
34750 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69  the BLOB accessi
34760 62 6c 65 20 76 69 61 20 74 68 65 20 0a 2a 2a 20  ble via the .** 
34770 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 65  successfully ope
34780 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  ned [BLOB handle
34790 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72  ] in its only ar
347a0 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a 2a 2a  gument.  ^The.**
347b0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f   incremental blo
347c0 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63  b I/O routines c
347d0 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20  an only read or 
347e0 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78 69 73  overwriting exis
347f0 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e  ting.** blob con
34800 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f  tent; they canno
34810 74 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a  t change the siz
34820 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a  e of a blob..**.
34830 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
34840 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
34850 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
34860 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has been cre
34870 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69  ated.** by a pri
34880 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
34890 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
348a0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
348b0 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a  which has not.**
348c0 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20   been closed by 
348d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
348e0 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67  ose()].  Passing
348f0 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74   any other point
34900 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73  er in.** to this
34910 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73   routine results
34920 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
34930 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
34940 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  irable behavior.
34950 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
34960 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74  blob_bytes(sqlit
34970 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a  e3_blob *);../*.
34980 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 61  ** CAPI3REF: Rea
34990 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c  d Data From A BL
349a0 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79  OB Incrementally
349b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
349c0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  nction is used t
349d0 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d  o read data from
349e0 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
349f0 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a  andle] into a.**
34a00 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64   caller-supplied
34a10 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73   buffer. N bytes
34a20 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
34a30 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ied into buffer 
34a40 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70  Z.** from the op
34a50 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e  en BLOB, startin
34a60 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
34a70 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  set.)^.**.** ^If
34a80 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20   offset iOffset 
34a90 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62  is less than N b
34aa0 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e  ytes from the en
34ab0 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a  d of the BLOB,.*
34ac0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
34ad0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
34ae0 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64   no data is read
34af0 2e 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f 66 66  .  ^If N or iOff
34b00 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  set is.** less t
34b10 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54  han zero, [SQLIT
34b20 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
34b30 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
34b40 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e 54 68   is read..** ^Th
34b50 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c  e size of the bl
34b60 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68  ob (and hence th
34b70 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20  e maximum value 
34b80 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a  of N+iOffset).**
34b90 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
34ba0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ed using the [sq
34bb0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
34bc0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
34bd0 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74  *.** ^An attempt
34be0 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 6e   to read from an
34bf0 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68   expired [BLOB h
34c00 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74  andle] fails wit
34c10 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f  h an.** error co
34c20 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
34c30 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  ORT]..**.** ^(On
34c40 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65   success, sqlite
34c50 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20 72 65  3_blob_read() re
34c60 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e  turns SQLITE_OK.
34c70 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61  .** Otherwise, a
34c80 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
34c90 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
34ca0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
34cb0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
34cc0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
34cd0 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c  y works on a [BL
34ce0 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68  OB handle] which
34cf0 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65   has been create
34d00 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20  d.** by a prior 
34d10 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
34d20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
34d30 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69  _open()] and whi
34d40 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65  ch has not.** be
34d50 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71  en closed by [sq
34d60 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
34d70 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e  ()].  Passing an
34d80 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20  y other pointer 
34d90 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f  in.** to this ro
34da0 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e  utine results in
34db0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
34dc0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
34dd0 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
34de0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
34df0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
34e00 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  e()]..*/.int sql
34e10 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73  ite3_blob_read(s
34e20 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76  qlite3_blob *, v
34e30 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69  oid *Z, int N, i
34e40 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a  nt iOffset);../*
34e50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72  .** CAPI3REF: Wr
34e60 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20  ite Data Into A 
34e70 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
34e80 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ly.**.** ^This f
34e90 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20  unction is used 
34ea0 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e  to write data in
34eb0 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  to an open [BLOB
34ec0 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a   handle] from a.
34ed0 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69  ** caller-suppli
34ee0 65 64 20 62 75 66 66 65 72 2e 20 5e 4e 20 62 79  ed buffer. ^N by
34ef0 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20  tes of data are 
34f00 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20  copied from the 
34f10 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f  buffer Z.** into
34f20 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20   the open BLOB, 
34f30 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
34f40 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a  et iOffset..**.*
34f50 2a 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f 42 20  * ^If the [BLOB 
34f60 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61  handle] passed a
34f70 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
34f80 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 65  ment was not ope
34f90 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69  ned for.** writi
34fa0 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61  ng (the flags pa
34fb0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
34fc0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
34fd0 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74   was zero),.** t
34fe0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
34ff0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  urns [SQLITE_REA
35000 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  DONLY]..**.** ^T
35010 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
35020 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65   only modify the
35030 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65   contents of the
35040 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20   BLOB; it is.** 
35050 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
35060 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a  increase the siz
35070 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69 6e  e of a BLOB usin
35080 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 5e  g this API..** ^
35090 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  If offset iOffse
350a0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e  t is less than N
350b0 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
350c0 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c  end of the BLOB,
350d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
350e0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
350f0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72  nd no data is wr
35100 69 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20 69 73  itten.  ^If N is
35110 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65  .** less than ze
35120 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ro [SQLITE_ERROR
35130 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
35140 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
35150 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a  tten..** The siz
35160 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61  e of the BLOB (a
35170 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78  nd hence the max
35180 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b  imum value of N+
35190 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20  iOffset).** can 
351a0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
351b0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
351c0 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
351d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
351e0 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77  ^An attempt to w
351f0 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72  rite to an expir
35200 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
35210 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
35220 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20  * error code of 
35230 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20  [SQLITE_ABORT]. 
35240 20 5e 57 72 69 74 65 73 20 74 6f 20 74 68 65 20   ^Writes to the 
35250 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72  BLOB that occurr
35260 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  ed.** before the
35270 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65   [BLOB handle] e
35280 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72  xpired are not r
35290 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68  olled back by th
352a0 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20  e.** expiration 
352b0 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74  of the handle, t
352c0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
352d0 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69  those changes mi
352e0 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e  ght.** have been
352f0 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
35300 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
35310 61 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42  at expired the B
35320 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72  LOB handle.** or
35330 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65   by other indepe
35340 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73  ndent statements
35350 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63  ..**.** ^(On suc
35360 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c  cess, sqlite3_bl
35370 6f 62 5f 77 72 69 74 65 28 29 20 72 65 74 75 72  ob_write() retur
35380 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a  ns SQLITE_OK..**
35390 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20   Otherwise, an  
353a0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
353b0 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  an [extended err
353c0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
353d0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  rned.)^.**.** Th
353e0 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
353f0 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42  works on a [BLOB
35400 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68   handle] which h
35410 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a  as been created.
35420 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75  ** by a prior su
35430 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
35440 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
35450 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68  pen()] and which
35460 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e   has not.** been
35470 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69   closed by [sqli
35480 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
35490 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20  ].  Passing any 
354a0 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e  other pointer in
354b0 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74  .** to this rout
354c0 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ine results in u
354d0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
354e0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
354f0 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  e behavior..**.*
35500 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
35510 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
35520 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
35530 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c  3_blob_write(sql
35540 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e  ite3_blob *, con
35550 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20  st void *z, int 
35560 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  n, int iOffset);
35570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35580 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53  : Virtual File S
35590 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a  ystem Objects.**
355a0 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69  .** A virtual fi
355b0 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69  lesystem (VFS) i
355c0 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  s an [sqlite3_vf
355d0 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61  s] object.** tha
355e0 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f  t SQLite uses to
355f0 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74   interact.** wit
35600 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  h the underlying
35610 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
35620 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20  m.  Most SQLite 
35630 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68  builds come with
35640 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66   a.** single def
35650 61 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73  ault VFS that is
35660 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
35670 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74   the host comput
35680 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73  er..** New VFSes
35690 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
356a0 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20  ed and existing 
356b0 56 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72  VFSes can be unr
356c0 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68  egistered..** Th
356d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  e following inte
356e0 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
356f0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ded..**.** ^The 
35700 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
35710 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
35720 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
35730 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74  o a VFS given it
35740 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61 6d 65  s name..** ^Name
35750 73 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69  s are case sensi
35760 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20  tive..** ^Names 
35770 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
35780 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
35790 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72 65 20  s..** ^If there 
357a0 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e  is no match, a N
357b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
357c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
357d0 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c  zVfsName is NULL
357e0 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
357f0 74 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65  t VFS is returne
35800 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20 56 46  d..**.** ^New VF
35810 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72  Ses are register
35820 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f  ed with sqlite3_
35830 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a  vfs_register()..
35840 2a 2a 20 5e 45 61 63 68 20 6e 65 77 20 56 46 53  ** ^Each new VFS
35850 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66   becomes the def
35860 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20  ault VFS if the 
35870 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73  makeDflt flag is
35880 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 61   set..** ^The sa
35890 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65  me VFS can be re
358a0 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
358b0 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20  e times without 
358c0 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f 20 6d  injury..** ^To m
358d0 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20  ake an existing 
358e0 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66  VFS into the def
358f0 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74  ault VFS, regist
35900 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77  er it again.** w
35910 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74  ith the makeDflt
35920 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74   flag set.  If t
35930 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53  wo different VFS
35940 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73  es with the.** s
35950 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67  ame name are reg
35960 69 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68  istered, the beh
35970 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
35980 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53  ed.  If a.** VFS
35990 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
359a0 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20  ith a name that 
359b0 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
359c0 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74  pty string,.** t
359d0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
359e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
359f0 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74 65 72  *.** ^Unregister
35a00 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20   a VFS with the 
35a10 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
35a20 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61  gister() interfa
35a30 63 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  ce..** ^(If the 
35a40 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75  default VFS is u
35a50 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f  nregistered, ano
35a60 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73  ther VFS is chos
35a70 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66  en as.** the def
35a80 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63  ault.  The choic
35a90 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46  e for the new VF
35aa0 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 29  S is arbitrary.)
35ab0 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73  ^.*/.sqlite3_vfs
35ac0 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   *sqlite3_vfs_fi
35ad0 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  nd(const char *z
35ae0 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71  VfsName);.int sq
35af0 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
35b00 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  er(sqlite3_vfs*,
35b10 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a   int makeDflt);.
35b20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  int sqlite3_vfs_
35b30 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74  unregister(sqlit
35b40 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e3_vfs*);../*.**
35b50 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
35b60 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  es.**.** The SQL
35b70 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
35b80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
35b90 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68   thread.** synch
35ba0 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75  ronization. Thou
35bb0 67 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 65  gh they are inte
35bc0 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61  nded for interna
35bd0 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
35be0 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69  te, code that li
35bf0 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69  nks against SQLi
35c00 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74  te is.** permitt
35c10 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66  ed to use any of
35c20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
35c30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
35c40 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f  e source code co
35c50 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20  ntains multiple 
35c60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
35c70 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65  ** of these mute
35c80 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20  x routines.  An 
35c90 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c  appropriate impl
35ca0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
35cb0 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61   selected automa
35cc0 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69  tically at compi
35cd0 6c 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68 65 20  le-time.  ^(The 
35ce0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70  following.** imp
35cf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65  lementations are
35d00 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
35d10 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a  e SQLite core:.*
35d20 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
35d30 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
35d40 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  _OS2.** <li>   S
35d50 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52  QLITE_MUTEX_PTHR
35d60 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  EAD.** <li>   SQ
35d70 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a  LITE_MUTEX_W32.*
35d80 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
35d90 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f  MUTEX_NOOP.** </
35da0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ul>)^.**.** ^The
35db0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f   SQLITE_MUTEX_NO
35dc0 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  OP implementatio
35dd0 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f  n is a set of ro
35de0 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64  utines.** that d
35df0 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b  oes no real lock
35e00 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f  ing and is appro
35e10 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69  priate for use i
35e20 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68  n.** a single-th
35e30 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
35e40 6f 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  on.  ^The SQLITE
35e50 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53  _MUTEX_OS2,.** S
35e60 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52  QLITE_MUTEX_PTHR
35e70 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f  EAD, and SQLITE_
35e80 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d  MUTEX_W32 implem
35e90 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
35ea0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
35eb0 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e   use on OS/2, Un
35ec0 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e  ix, and Windows.
35ed0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
35ee0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
35ef0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d  ith the SQLITE_M
35f00 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70  UTEX_APPDEF prep
35f10 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72  rocessor.** macr
35f20 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20  o defined (with 
35f30 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  "-DSQLITE_MUTEX_
35f40 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e  APPDEF=1"), then
35f50 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70   no mutex.** imp
35f60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69  lementation is i
35f70 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65  ncluded with the
35f80 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69   library. In thi
35f90 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70  s case the.** ap
35fa0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
35fb0 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d  upply a custom m
35fc0 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
35fd0 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ion using the.**
35fe0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
35ff0 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66  MUTEX] option of
36000 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   the sqlite3_con
36010 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  fig() function.*
36020 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67  * before calling
36030 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
36040 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68  ize() or any oth
36050 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65  er public sqlite
36060 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  3_.** function t
36070 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  hat calls sqlite
36080 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 29  3_initialize().)
36090 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
360a0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
360b0 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63  () routine alloc
360c0 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75  ates a new.** mu
360d0 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20  tex and returns 
360e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
360f0 20 5e 49 66 20 69 74 20 72 65 74 75 72 6e 73 20   ^If it returns 
36100 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61  NULL.** that mea
36110 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20  ns that a mutex 
36120 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c  could not be all
36130 6f 63 61 74 65 64 2e 20 20 5e 53 51 4c 69 74 65  ocated.  ^SQLite
36140 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20  .** will unwind 
36150 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65  its stack and re
36160 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20  turn an error.  
36170 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ^(The argument.*
36180 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  * to sqlite3_mut
36190 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e  ex_alloc() is on
361a0 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
361b0 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  er constants:.**
361c0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
361d0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46    SQLITE_MUTEX_F
361e0 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  AST.** <li>  SQL
361f0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
36200 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
36210 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
36220 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20  _MASTER.** <li> 
36230 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
36240 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e  ATIC_MEM.** <li>
36250 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
36260 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c  TATIC_MEM2.** <l
36270 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
36280 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20  _STATIC_PRNG.** 
36290 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
362a0 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a  EX_STATIC_LRU.**
362b0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
362c0 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a  TEX_STATIC_LRU2.
362d0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
362e0 20 5e 54 68 65 20 66 69 72 73 74 20 74 77 6f 20   ^The first two 
362f0 63 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c 49 54  constants (SQLIT
36300 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64  E_MUTEX_FAST and
36310 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
36320 43 55 52 53 49 56 45 29 0a 2a 2a 20 63 61 75 73  CURSIVE).** caus
36330 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
36340 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74  alloc() to creat
36350 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78  e.** a new mutex
36360 2e 20 20 5e 54 68 65 20 6e 65 77 20 6d 75 74 65  .  ^The new mute
36370 78 20 69 73 20 72 65 63 75 72 73 69 76 65 20 77  x is recursive w
36380 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
36390 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73  _RECURSIVE.** is
363a0 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65   used but not ne
363b0 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65  cessarily so whe
363c0 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  n SQLITE_MUTEX_F
363d0 41 53 54 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20  AST is used..** 
363e0 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  The mutex implem
363f0 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  entation does no
36400 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61  t need to make a
36410 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
36420 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d  between SQLITE_M
36430 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61  UTEX_RECURSIVE a
36440 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
36450 46 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a  FAST if it does.
36460 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20  ** not want to. 
36470 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e   ^SQLite will on
36480 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63  ly request a rec
36490 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a  ursive mutex in.
364a0 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69  ** cases where i
364b0 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f  t really needs o
364c0 6e 65 2e 20 20 5e 49 66 20 61 20 66 61 73 74 65  ne.  ^If a faste
364d0 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20  r non-recursive 
364e0 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
364f0 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  ntation is avail
36500 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74  able on the host
36510 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d   platform, the m
36520 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a  utex subsystem.*
36530 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73  * might return s
36540 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72  uch a mutex in r
36550 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54  esponse to SQLIT
36560 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a  E_MUTEX_FAST..**
36570 0a 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72 20 61  .** ^The other a
36580 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72  llowed parameter
36590 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  s to sqlite3_mut
365a0 65 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e 79 74  ex_alloc() (anyt
365b0 68 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20 74 68  hing other.** th
365c0 61 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  an SQLITE_MUTEX_
365d0 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f  FAST and SQLITE_
365e0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29  MUTEX_RECURSIVE)
365f0 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20   each return.** 
36600 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
36610 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e  tatic preexistin
36620 67 20 6d 75 74 65 78 2e 20 20 5e 53 69 78 20 73  g mutex.  ^Six s
36630 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
36640 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65  e.** used by the
36650 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
36660 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74   of SQLite.  Fut
36670 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
36680 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64  SQLite.** may ad
36690 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61  d additional sta
366a0 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74  tic mutexes.  St
366b0 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
366c0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
366d0 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f   use by SQLite o
366e0 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
366f0 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ns that use SQLi
36700 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  te mutexes shoul
36710 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68  d.** use only th
36720 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
36730 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  s returned by SQ
36740 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
36750 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  or.** SQLITE_MUT
36760 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a  EX_RECURSIVE..**
36770 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 69  .** ^Note that i
36780 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e  f one of the dyn
36790 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d  amic mutex param
367a0 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55  eters (SQLITE_MU
367b0 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53  TEX_FAST.** or S
367c0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
367d0 52 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74  RSIVE) is used t
367e0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  hen sqlite3_mute
367f0 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74  x_alloc().** ret
36800 75 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74  urns a different
36810 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20   mutex on every 
36820 63 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f 72 20  call.  ^But for 
36830 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75  the static.** mu
36840 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73  tex types, the s
36850 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74  ame mutex is ret
36860 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63  urned on every c
36870 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  all that has.** 
36880 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75  the same type nu
36890 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
368a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66   sqlite3_mutex_f
368b0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65  ree() routine de
368c0 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76  allocates a prev
368d0 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61  iously.** alloca
368e0 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  ted dynamic mute
368f0 78 2e 20 20 5e 53 51 4c 69 74 65 20 69 73 20 63  x.  ^SQLite is c
36900 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f  areful to deallo
36910 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79  cate every.** dy
36920 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74  namic mutex that
36930 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20   it allocates.  
36940 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  The dynamic mute
36950 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  xes must not be 
36960 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74  in.** use when t
36970 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  hey are dealloca
36980 74 65 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67  ted.  Attempting
36990 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61   to deallocate a
369a0 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78   static.** mutex
369b0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
369c0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20  fined behavior. 
369d0 20 5e 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64   ^SQLite never d
369e0 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20  eallocates.** a 
369f0 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
36a00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36a10 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61  _mutex_enter() a
36a20 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
36a30 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20  _try() routines 
36a40 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e  attempt.** to en
36a50 74 65 72 20 61 20 6d 75 74 65 78 2e 20 20 5e 49  ter a mutex.  ^I
36a60 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
36a70 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68   is already with
36a80 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a  in the mutex,.**
36a90 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
36aa0 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63  nter() will bloc
36ab0 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75  k and sqlite3_mu
36ac0 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72  tex_try() will r
36ad0 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
36ae0 42 55 53 59 2e 20 20 5e 54 68 65 20 73 71 6c 69  BUSY.  ^The sqli
36af0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
36b00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36b10 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a  s [SQLITE_OK].**
36b20 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c   upon successful
36b30 20 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74 65 78   entry.  ^(Mutex
36b40 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
36b50 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
36b60 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62  _RECURSIVE can b
36b70 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70  e entered multip
36b80 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20  le times by the 
36b90 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20  same thread..** 
36ba0 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68  In such cases th
36bb0 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74  e,.** mutex must
36bc0 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71   be exited an eq
36bd0 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  ual number of ti
36be0 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68  mes before anoth
36bf0 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e  er thread.** can
36c00 20 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49 66 20   enter.)^  ^(If 
36c10 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
36c20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61  tries to enter a
36c30 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  ny other.** kind
36c40 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74   of mutex more t
36c50 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65  han once, the be
36c60 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
36c70 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ned..** SQLite w
36c80 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69  ill never exhibi
36c90 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69  t.** such behavi
36ca0 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73  or in its own us
36cb0 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 29 5e 0a  e of mutexes.)^.
36cc0 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73 79 73  **.** ^(Some sys
36cd0 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c  tems (for exampl
36ce0 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64  e, Windows 95) d
36cf0 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68  o not support th
36d00 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  e operation.** i
36d10 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71  mplemented by sq
36d20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
36d30 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73  ).  On those sys
36d40 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75  tems, sqlite3_mu
36d50 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c  tex_try().** wil
36d60 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
36d70 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54 68  SQLITE_BUSY.  Th
36d80 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e  e SQLite core on
36d90 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20  ly ever uses.** 
36da0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
36db0 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69  y() as an optimi
36dc0 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69  zation so this i
36dd0 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68  s acceptable beh
36de0 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  avior.)^.**.** ^
36df0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
36e00 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e  x_leave() routin
36e10 65 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20  e exits a mutex 
36e20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76  that was.** prev
36e30 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62  iously entered b
36e40 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  y the same threa
36e50 64 2e 20 20 20 5e 28 54 68 65 20 62 65 68 61 76  d.   ^(The behav
36e60 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
36e70 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78  ned if the mutex
36e80 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
36e90 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65  y entered by the
36ea0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  .** calling thre
36eb0 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72  ad or is not cur
36ec0 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64  rently allocated
36ed0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
36ee0 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65  * never do eithe
36ef0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  r.)^.**.** ^If t
36f00 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  he argument to s
36f10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
36f20 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75  er(), sqlite3_mu
36f30 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a  tex_try(), or.**
36f40 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c   sqlite3_mutex_l
36f50 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c  eave() is a NULL
36f60 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61   pointer, then a
36f70 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  ll three routine
36f80 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e  s.** behave as n
36f90 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  o-ops..**.** See
36fa0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
36fb0 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e  mutex_held()] an
36fc0 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d [sqlite3_mutex
36fd0 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a  _notheld()]..*/.
36fe0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73  sqlite3_mutex *s
36ff0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
37000 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  oc(int);.void sq
37010 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
37020 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
37030 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
37040 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74  utex_enter(sqlit
37050 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
37060 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
37070 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  y(sqlite3_mutex*
37080 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37090 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69  mutex_leave(sqli
370a0 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a  te3_mutex*);../*
370b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
370c0 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  tex Methods Obje
370d0 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
370e0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
370f0 75 63 74 75 72 65 20 64 65 66 69 6e 65 73 20 74  ucture defines t
37100 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75  he low-level rou
37110 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f  tines.** used to
37120 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73   allocate and us
37130 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a  e mutexes..**.**
37140 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65   Usually, the de
37150 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c  fault mutex impl
37160 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76  ementations prov
37170 69 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  ided by SQLite a
37180 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74  re.** sufficient
37190 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 75 73  , however the us
371a0 65 72 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f  er has the optio
371b0 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e  n of substitutin
371c0 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d  g a custom.** im
371d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
371e0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70   specialized dep
371f0 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74  loyments or syst
37200 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53 51  ems for which SQ
37210 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  Lite.** does not
37220 20 70 72 6f 76 69 64 65 20 61 20 73 75 69 74 61   provide a suita
37230 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
37240 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65  on. In this case
37250 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72  , the user.** cr
37260 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61  eates and popula
37270 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  tes an instance 
37280 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
37290 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20  e to pass.** to 
372a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
372b0 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20   along with the 
372c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
372d0 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  UTEX] option..**
372e0 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61   Additionally, a
372f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
37300 69 73 20 73 74 72 75 63 74 75 72 65 20 63 61 6e  is structure can
37310 20 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a   be used as an.*
37320 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c  * output variabl
37330 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20  e when querying 
37340 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74  the system for t
37350 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78  he current mutex
37360 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
37370 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53  on, using the [S
37380 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
37390 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a  MUTEX] option..*
373a0 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78  *.** ^The xMutex
373b0 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69  Init method defi
373c0 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75  ned by this stru
373d0 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64  cture is invoked
373e0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73   as.** part of s
373f0 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61  ystem initializa
37400 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69  tion by the sqli
37410 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
37420 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 54   function..** ^T
37430 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f  he xMutexInit ro
37440 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 20 62  utine is calle b
37450 79 20 53 51 4c 69 74 65 20 65 78 61 63 74 6c 79  y SQLite exactly
37460 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a   once for each.*
37470 2a 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  * effective call
37480 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69   to [sqlite3_ini
37490 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a  tialize()]..**.*
374a0 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64  * ^The xMutexEnd
374b0 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20   method defined 
374c0 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72  by this structur
374d0 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a  e is invoked as.
374e0 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65  ** part of syste
374f0 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20 74 68  m shutdown by th
37500 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
37510 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54  wn() function. T
37520 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
37530 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74  tion of this met
37540 68 6f 64 20 69 73 20 65 78 70 65 63 74 65 64 20  hod is expected 
37550 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f  to release all o
37560 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65  utstanding.** re
37570 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e 65 64  sources obtained
37580 20 62 79 20 74 68 65 20 6d 75 74 65 78 20 6d 65   by the mutex me
37590 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61  thods implementa
375a0 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79  tion, especially
375b0 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 69 6e  .** those obtain
375c0 65 64 20 62 79 20 74 68 65 20 78 4d 75 74 65 78  ed by the xMutex
375d0 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 20 5e 54  Init method.  ^T
375e0 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a  he xMutexEnd().*
375f0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  * interface is i
37600 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f  nvoked exactly o
37610 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c  nce for each cal
37620 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68  l to [sqlite3_sh
37630 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a  utdown()]..**.**
37640 20 5e 28 54 68 65 20 72 65 6d 61 69 6e 69 6e 67   ^(The remaining
37650 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64   seven methods d
37660 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73  efined by this s
37670 74 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78  tructure (xMutex
37680 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78  Alloc,.** xMutex
37690 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65  Free, xMutexEnte
376a0 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d  r, xMutexTry, xM
376b0 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65  utexLeave, xMute
376c0 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75  xHeld and.** xMu
376d0 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c  texNotheld) impl
376e0 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77  ement the follow
376f0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28  ing interfaces (
37700 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a  respectively):.*
37710 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
37720 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
37730 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c  tex_alloc()] </l
37740 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
37750 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
37760 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  e()] </li>.**   
37770 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
37780 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f  utex_enter()] </
37790 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
377a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
377b0 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  y()] </li>.**   
377c0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
377d0 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f  utex_leave()] </
377e0 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
377f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
37800 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ld()] </li>.**  
37810 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
37820 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
37830 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29   </li>.** </ul>)
37840 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79  ^.**.** The only
37850 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 74   difference is t
37860 68 61 74 20 74 68 65 20 70 75 62 6c 69 63 20 73  hat the public s
37870 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74  qlite3_XXX funct
37880 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a  ions enumerated.
37890 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c  ** above silentl
378a0 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76  y ignore any inv
378b0 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61  ocations that pa
378c0 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ss a NULL pointe
378d0 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
378e0 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61  a valid mutex ha
378f0 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d  ndle. The implem
37900 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
37910 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64   methods defined
37920 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74 72 75  .** by this stru
37930 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65  cture are not re
37940 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65  quired to handle
37950 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20   this case, the 
37960 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61  results.** of pa
37970 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
37980 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
37990 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61  a valid mutex ha
379a0 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e  ndle are undefin
379b0 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69  ed.** (i.e. it i
379c0 73 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20  s acceptable to 
379d0 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65  provide an imple
379e0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73  mentation that s
379f0 65 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69  egfaults if.** i
37a00 74 20 69 73 20 70 61 73 73 65 64 20 61 20 4e 55  t is passed a NU
37a10 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2a 0a  LL pointer)..**.
37a20 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69  ** The xMutexIni
37a30 74 28 29 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  t() method must 
37a40 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
37a50 5e 49 74 20 6d 75 73 74 20 62 65 20 68 61 72 6d  ^It must be harm
37a60 6c 65 73 73 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  less to.** invok
37a70 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d  e xMutexInit() m
37a80 75 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74  utiple times wit
37a90 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
37aa0 63 65 73 73 20 61 6e 64 20 77 69 74 68 6f 75 74  cess and without
37ab0 0a 2a 2a 20 69 6e 74 65 72 76 65 6e 69 6e 67 20  .** intervening 
37ac0 63 61 6c 6c 73 20 74 6f 20 78 4d 75 74 65 78 45  calls to xMutexE
37ad0 6e 64 28 29 2e 20 20 53 65 63 6f 6e 64 20 61 6e  nd().  Second an
37ae0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
37af0 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75 74 65 78 49  ls to.** xMutexI
37b00 6e 69 74 28 29 20 6d 75 73 74 20 62 65 20 6e 6f  nit() must be no
37b10 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 78 4d 75  -ops..**.** ^xMu
37b20 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 6e  texInit() must n
37b30 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65  ot use SQLite me
37b40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
37b50 28 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  ([sqlite3_malloc
37b60 28 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73 20 61  ()].** and its a
37b70 73 73 6f 63 69 61 74 65 73 29 2e 20 20 5e 53 69  ssociates).  ^Si
37b80 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 74 65 78 41  milarly, xMutexA
37b90 6c 6c 6f 63 28 29 20 6d 75 73 74 20 6e 6f 74 20  lloc() must not 
37ba0 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72  use SQLite memor
37bb0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
37bc0 66 6f 72 20 61 20 73 74 61 74 69 63 20 6d 75 74  for a static mut
37bd0 65 78 2e 20 20 5e 48 6f 77 65 76 65 72 20 78 4d  ex.  ^However xM
37be0 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61 79 20  utexAlloc() may 
37bf0 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 65  use SQLite.** me
37c00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
37c10 66 6f 72 20 61 20 66 61 73 74 20 6f 72 20 72 65  for a fast or re
37c20 63 75 72 73 69 76 65 20 6d 75 74 65 78 2e 0a 2a  cursive mutex..*
37c30 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
37c40 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78 4d 75  l invoke the xMu
37c50 74 65 78 45 6e 64 28 29 20 6d 65 74 68 6f 64 20  texEnd() method 
37c60 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 68  when [sqlite3_sh
37c70 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a 2a 20  utdown()] is.** 
37c80 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e 6c 79  called, but only
37c90 20 69 66 20 74 68 65 20 70 72 69 6f 72 20 63 61   if the prior ca
37ca0 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e 69 74  ll to xMutexInit
37cb0 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49 54 45   returned SQLITE
37cc0 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75 74 65  _OK..** If xMute
37cd0 78 49 6e 69 74 20 66 61 69 6c 73 20 69 6e 20 61  xInit fails in a
37ce0 6e 79 20 77 61 79 2c 20 69 74 20 69 73 20 65 78  ny way, it is ex
37cf0 70 65 63 74 65 64 20 74 6f 20 63 6c 65 61 6e 20  pected to clean 
37d00 75 70 20 61 66 74 65 72 20 69 74 73 65 6c 66 0a  up after itself.
37d10 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72 65 74 75  ** prior to retu
37d20 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65 64 65  rning..*/.typede
37d30 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
37d40 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73  _mutex_methods s
37d50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
37d60 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
37d70 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
37d80 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75  ds {.  int (*xMu
37d90 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a  texInit)(void);.
37da0 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e    int (*xMutexEn
37db0 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69  d)(void);.  sqli
37dc0 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75  te3_mutex *(*xMu
37dd0 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a  texAlloc)(int);.
37de0 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46    void (*xMutexF
37df0 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  ree)(sqlite3_mut
37e00 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a  ex *);.  void (*
37e10 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c  xMutexEnter)(sql
37e20 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20  ite3_mutex *);. 
37e30 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79   int (*xMutexTry
37e40 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
37e50 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  *);.  void (*xMu
37e60 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65  texLeave)(sqlite
37e70 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e  3_mutex *);.  in
37e80 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28  t (*xMutexHeld)(
37e90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
37ea0 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
37eb0 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33  Notheld)(sqlite3
37ec0 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f  _mutex *);.};../
37ed0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
37ee0 75 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f  utex Verificatio
37ef0 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
37f00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
37f10 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71  ex_held() and sq
37f20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
37f30 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a  eld() routines.*
37f40 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  * are intended f
37f50 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73  or use inside as
37f60 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
37f70 73 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20  s.  ^The SQLite 
37f80 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73  core.** never us
37f90 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  es these routine
37fa0 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 65 20  s except inside 
37fb0 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64 20  an assert() and 
37fc0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
37fd0 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20 66  are advised to f
37fe0 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f  ollow the lead o
37ff0 66 20 74 68 65 20 63 6f 72 65 2e 20 20 5e 54 68  f the core.  ^Th
38000 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e  e SQLite core on
38010 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69  ly.** provides i
38020 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
38030 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
38040 73 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  s when it is com
38050 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  piled.** with th
38060 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66  e SQLITE_DEBUG f
38070 6c 61 67 2e 20 20 5e 45 78 74 65 72 6e 61 6c 20  lag.  ^External 
38080 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
38090 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c  tions.** are onl
380a0 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72  y required to pr
380b0 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74  ovide these rout
380c0 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44  ines if SQLITE_D
380d0 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e  EBUG is.** defin
380e0 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47  ed and if NDEBUG
380f0 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e   is not defined.
38100 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
38110 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65  utines should re
38120 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65  turn true if the
38130 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72 20   mutex in their 
38140 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68  argument.** is h
38150 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c  eld or not held,
38160 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62   respectively, b
38170 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  y the calling th
38180 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  read..**.** ^The
38190 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
381a0 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20  is not required 
381b0 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 73  to provided vers
381c0 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ions of these.**
381d0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61   routines that a
381e0 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66  ctually work. If
381f0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
38200 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f  ion does not pro
38210 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20  vide working.** 
38220 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
38230 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73  e routines, it s
38240 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70  hould at least p
38250 72 6f 76 69 64 65 20 73 74 75 62 73 20 74 68 61  rovide stubs tha
38260 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75  t always.** retu
38270 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20  rn true so that 
38280 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74  one does not get
38290 20 73 70 75 72 69 6f 75 73 20 61 73 73 65 72 74   spurious assert
382a0 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a  ion failures..**
382b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75  .** ^If the argu
382c0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
382d0 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20  mutex_held() is 
382e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
382f0 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  hen.** the routi
38300 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ne should return
38310 20 31 2e 20 20 20 54 68 69 73 20 73 65 65 6d 73   1.   This seems
38320 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69   counter-intuiti
38330 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61  ve since.** clea
38340 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63 61  rly the mutex ca
38350 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20  nnot be held if 
38360 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73  it does not exis
38370 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74  t.  But the.** t
38380 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75  he reason the mu
38390 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69  tex does not exi
383a0 73 74 20 69 73 20 62 65 63 61 75 73 65 20 74 68  st is because th
383b0 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a  e build is not.*
383c0 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e  * using mutexes.
383d0 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20    And we do not 
383e0 77 61 6e 74 20 74 68 65 20 61 73 73 65 72 74 28  want the assert(
383f0 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
38400 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
38410 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
38420 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e   to fail, so a n
38430 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69  on-zero return i
38440 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72  s.** the appropr
38450 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f  iate thing to do
38460 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
38470 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 0a  mutex_notheld().
38480 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f  ** interface sho
38490 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  uld also return 
384a0 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e  1 when given a N
384b0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
384c0 23 69 66 6e 64 65 66 20 4e 44 45 42 55 47 0a 69  #ifndef NDEBUG.i
384d0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nt sqlite3_mutex
384e0 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  _held(sqlite3_mu
384f0 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tex*);.int sqlit
38500 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
38510 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
38520 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
38530 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
38540 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Types.**.** The 
38550 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
38560 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63  lloc()] interfac
38570 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  e takes a single
38580 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69   argument.** whi
38590 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  ch is one of the
385a0 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
385b0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ants..**.** The 
385c0 73 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75  set of static mu
385d0 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65  texes may change
385e0 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65   from one SQLite
385f0 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a   release to the.
38600 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
38610 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72  ations that over
38620 72 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ride the built-i
38630 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75  n mutex logic mu
38640 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65  st be.** prepare
38650 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65  d to accommodate
38660 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74   additional stat
38670 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23  ic mutexes..*/.#
38680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
38690 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20  TEX_FAST        
386a0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
386b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
386c0 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23  RSIVE        1.#
386d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
386e0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
386f0 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  R    2.#define S
38700 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
38710 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20  IC_MEM       3  
38720 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  /* sqlite3_mallo
38730 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  c() */.#define S
38740 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
38750 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20  IC_MEM2      4  
38760 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23  /* NOT USED */.#
38770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
38780 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20  TEX_STATIC_OPEN 
38790 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
387a0 65 33 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f  e3BtreeOpen() */
387b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
387c0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
387d0 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  G      5  /* sql
387e0 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f  ite3_random() */
387f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38800 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
38810 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75         6  /* lru
38820 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64   page list */.#d
38830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
38840 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20  EX_STATIC_LRU2  
38850 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61      7  /* lru pa
38860 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  ge list */../*.*
38870 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
38880 69 65 76 65 20 74 68 65 20 6d 75 74 65 78 20 66  ieve the mutex f
38890 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
388a0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
388b0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  This interface r
388c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
388d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
388e0 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  tex] object that
388f0 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20   .** serializes 
38900 61 63 63 65 73 73