/ Hex Artifact Content
Login

Artifact ad55acc42422c461719f3adaee434836ab00677b:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73  3_close()].** is
23f0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
2400: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2410: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
2420: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2430: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2440: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2450: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2460: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2470: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
2480: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
2490: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24a0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24b0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24d0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
24e0: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
24f0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2500: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2510: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2520: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2530: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2540: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2550: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2560: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2570: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
2580: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
2590: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25a0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25b0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25d0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
25e0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
25f0: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2600: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2610: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2620: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2630: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2640: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2650: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2660: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2670: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2680: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2690: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26a0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26b0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26c0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26d0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
26e0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
26f0: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2700: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2710: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2720: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2730: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2740: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2750: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2760: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2770: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
2780: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2790: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27a0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27b0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27d0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
27e0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
27f0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2800: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2810: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2820: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2830: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2840: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2850: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2860: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2870: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2880: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2890: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28a0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28b0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28d0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
28e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
28f0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2900: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2910: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2920: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2930: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2940: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2950: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2960: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2970: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2980: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2990: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29a0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29b0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29d0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
29e0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
29f0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a00: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2a30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2a40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2a50: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2a60: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2a70: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
2a80: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
2a90: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2aa0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2ab0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2ac0: 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75  associated resou
2ad0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2ae0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ated..**.** Appl
2af0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73  ications must [s
2b00: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2b10: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
2b20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b30: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  ents].** and [sq
2b40: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2b50: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2b60: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73  LOB handles] ass
2b70: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
2b80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2b90: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ba0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2bb0: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2bc0: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2bd0: 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ose() is called 
2be0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
2c00: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
2c10: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
2c20: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f  ed statements] o
2c30: 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  r [BLOB handles]
2c40: 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  , then it return
2c50: 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  s.** SQLITE_BUSY
2c60: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c  ..**.** ^If [sql
2c70: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73  ite3_close()] is
2c80: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61   invoked while a
2c90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2ca0: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
2cb0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
2cc0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
2cd0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
2ce0: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
2cf0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2d00: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  )] must be eithe
2d10: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
2d20: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ter or an [sqlit
2d30: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  e3] object point
2d40: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  er obtained.** f
2d50: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
2d60: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2d70: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
2d80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2d90: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
2da0: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
2db0: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
2dc0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68  te3_close() with
2dd0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2de0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a  argument is a .*
2df0: 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  * harmless no-op
2e00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e10: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2e20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2e30: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
2e40: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
2e50: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
2e60: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
2e70: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
2e80: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
2e90: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
2ea0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2eb0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2ec0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2ed0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ee0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2ef0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f00: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2f10: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2f20: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
2f30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2f40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
2f50: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
2f60: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
2f70: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f80: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2f90: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2fa0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
2fb0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
2fc0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
2fd0: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
2fe0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
2ff0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3000: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3010: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3020: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3030: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3040: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3050: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
3060: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
3070: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
3080: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3090: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
30a0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
30b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
30c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30d0: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
30e0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
30f0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3100: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3110: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3120: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3130: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3140: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3150: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
3160: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
3170: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
3180: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
3190: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
31a0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
31b0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
31c0: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
31d0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
31e0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
31f0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3200: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3210: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3220: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3230: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3240: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3250: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3260: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3270: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3280: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3290: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
32a0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
32b0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
32c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
32e0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
32f0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3300: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3310: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3320: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3330: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3340: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3350: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3360: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3370: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3380: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3390: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
33a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
33b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
33c0: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
33d0: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
33e0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
33f0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3400: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3410: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3420: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3430: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3440: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3450: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3460: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3470: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
3480: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3490: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
34a0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
34b0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
34c0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
34d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
34e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
34f0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3500: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3510: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3520: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3530: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3540: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3550: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3560: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3570: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3580: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3590: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
35a0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
35b0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
35c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
35d0: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
35e0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
35f0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3600: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3610: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3620: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3630: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3640: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3650: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3660: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3670: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3680: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3690: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
36a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
36b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
36c0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
36d0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
36e0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
36f0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3700: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3710: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3720: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3730: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3740: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3750: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3760: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3770: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3780: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3790: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
37a0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
37b0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
37c0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
37d0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
37e0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
37f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3800: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3810: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3820: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3830: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3840: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3850: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3860: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3870: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3880: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3890: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
38a0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
38b0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
38c0: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
38d0: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
38e0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
38f0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3900: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3910: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3920: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3930: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3940: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3950: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3960: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3970: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3980: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3990: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
39a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
39b0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
39c0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
39d0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
39e0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
39f0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3a00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3a10: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3a20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3a30: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
3a40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a50: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3a60: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3a90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3aa0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ab0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3ac0: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
3ad0: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
3ae0: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
3af0: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
3b00: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3b10: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
3b20: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
3b30: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
3b40: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
3b50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
3b60: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 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 20 20 2f                 /
3b90: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3ba0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3bb0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3be0: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
3bf0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
3c00: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3c10: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
3c20: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
3c30: 2f 0a 20 20 76 6f 69 64 20 2a 2c 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 20 20 2f                 /
3c60: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3c70: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3c80: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **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 20 20 2f 2a 20 45 72             /* Er
3cb0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3cc0: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3cd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3ce0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
3cf0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3d00: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3d10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
3d20: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
3d30: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
3d40: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
3d50: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
3d60: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
3d70: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
3d80: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
3d90: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
3da0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
3db0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3dc0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
3dd0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
3de0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
3df0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3e00: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
3e10: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3e20: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3e30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
3e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
3e50: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
3e60: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
3e70: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
3e80: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
3e90: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3ea0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3eb0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3ec0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3ed0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3ef0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3f00: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3f10: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f30: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3f40: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
3f50: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
3f60: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
3f70: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3f80: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
3f90: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
3fa0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3fb0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
3fc0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
3fd0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
3fe0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
3ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
4000: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
4010: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
4020: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4040: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4050: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4060: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4070: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4080: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4090: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
40a0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
40b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40c0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
40d0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
40e0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
40f0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
4100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
4110: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
4120: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
4130: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
4140: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4160: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4170: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4180: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4190: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
41a0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
41b0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
41c0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
41d0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
41e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41f0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
4200: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
4210: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
4220: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
4230: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4240: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4250: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4260: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4270: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4290: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
42a0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
42b0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
42c0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
42d0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
42e0: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
42f0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
4300: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
4310: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
4320: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
4330: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4360: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4370: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4380: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4390: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
43a0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
43b0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
43c0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
43d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
43e0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
43f0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
4400: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
4410: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
4420: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
4430: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
4440: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4460: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4470: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4480: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
44a0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
44b0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
44c0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
44d0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
44e0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
44f0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
4500: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
4510: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4520: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
4530: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
4540: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4550: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4560: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4570: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4580: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4590: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
45a0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
45b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
45c0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
45d0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
45e0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
45f0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4600: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
4610: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4620: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4630: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4640: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4650: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4660: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4670: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4680: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4690: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
46a0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
46b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
46c0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
46d0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
46e0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
46f0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4700: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4710: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4720: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4730: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4740: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4750: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4760: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4770: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4780: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4790: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
47a0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
47b0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
47c0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
47d0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
47e0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
47f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4800: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4810: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4820: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4830: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4840: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4850: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4860: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4870: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4880: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4890: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
48a0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
48b0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
48c0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
48d0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
48e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
48f0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4900: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4910: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4920: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4930: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4940: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4950: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4960: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4970: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4980: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4990: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
49a0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
49b0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
49c0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
49d0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
49e0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
49f0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4a00: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4a10: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4a20: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4a30: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4a40: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4a50: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4a60: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4a70: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4a80: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4a90: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4aa0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4ab0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4ac0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4ad0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4ae0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4af0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4b00: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4b10: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
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 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4b70: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
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 57 52 49 54 45 20 20  TE_IOERR_WRITE  
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 33 3c 3c 38  TE_IOERR | (3<<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 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4bf0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<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 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
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 35 3c 3c 38 29 29  _IOERR | (5<<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 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
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 36 3c 3c 38 29 29 0a  IOERR | (6<<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 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
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 37 3c 3c 38 29 29 0a 23  OERR | (7<<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 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
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 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<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 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
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 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4d50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4d60: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4d70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4d80: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4da0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4db0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4dc0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4de0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4df0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e00: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e20: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e40: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e60: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4e70: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4e80: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ea0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ec0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f00: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f20: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4f30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f40: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f60: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
4f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f80: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
4f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fa0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
4fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fc0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
4fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fe0: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
4ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5000: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
5010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5020: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
5030: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5040: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5060: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5070: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5080: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
50a0: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
50b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
50c0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
50e0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5100: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5120: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5130: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5140: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
51b0: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
51c0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
51d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51e0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
51f0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5200: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5230: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5240: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5250: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5260: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5270: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5280: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5290: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
52a0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
52b0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
52c0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
52d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
52e0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
52f0: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5300: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5310: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5320: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5340: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5350: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5360: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5370: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5380: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5390: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
53a0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
53b0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
53c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
53d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
53e0: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
53f0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5400: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5410: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5430: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5440: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5450: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5470: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5480: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5490: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
54a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
54b0: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
54c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
54d0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
54e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
54f0: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
5500: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
5510: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5520: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5540: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
5550: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
5560: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5580: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
5590: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
55a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
55b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
55c0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
55d0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
55e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
55f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5600: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
5610: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
5620: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5640: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
5650: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
5660: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5670: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5680: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
5690: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
56a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
56b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
56c0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
56d0: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
56e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
56f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5700: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
5710: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
5720: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5730: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5750: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
5760: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
5770: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5780: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5790: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
57a0: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
57b0: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
57c0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
57d0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
57e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
57f0: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
5800: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
5810: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5820: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5840: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
5850: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
5860: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5870: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
5880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5890: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
58a0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
58b0: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
58c0: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
58d0: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
58e0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
58f0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
5900: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5910: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
5920: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
5930: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5940: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5950: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5960: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5970: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5980: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5990: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
59a0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
59b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
59c0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
59d0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
59e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
59f0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
5a00: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
5a10: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
5a20: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5a30: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5a40: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5a50: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5a60: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5a70: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5a80: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5a90: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5aa0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5ab0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5ac0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5ad0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
5ae0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5af0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
5b00: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
5b10: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
5b20: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5b30: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5b40: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5b50: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5b60: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5b70: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5b80: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5b90: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5ba0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5bb0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5bc0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5bd0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
5be0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
5bf0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
5c00: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
5c10: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
5c20: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
5c30: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
5c40: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
5c50: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
5c60: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
5c70: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
5c80: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
5c90: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
5ca0: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
5cb0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
5cc0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
5cd0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
5ce0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
5cf0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
5d00: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
5d10: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
5d20: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
5d30: 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65  nchanged..*/.#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5d50: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
5d60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5d70: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
5d80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
5d90: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
5da0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
5db0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5dc0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
5dd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5de0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
5df0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
5e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5e10: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
5e20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5e30: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
5e40: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
5e50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5e60: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
5e70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5e80: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5e90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ea0: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
5eb0: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
5ec0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5ed0: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
5ee0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ef0: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
5f00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5f10: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
5f20: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
5f30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5f40: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
5f50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5f60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5f70: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5f80: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
5f90: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
5fa0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
5fb0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
5fc0: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
5fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fe0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
5ff0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6000: 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0001000../*.** C
6010: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6020: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
6030: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
6040: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
6050: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6060: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
6070: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
6080: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6090: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
60a0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
60b0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
60c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
60d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
60e0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
60f0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6100: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6110: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6130: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
6140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6150: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
6160: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6170: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6180: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6190: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
61a0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
61b0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
61c0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
61d0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
61e0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
61f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6200: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6210: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6220: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6230: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6240: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
6250: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
6260: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6270: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
6280: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
6290: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
62a0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
62b0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
62c0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
62d0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
62e0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
62f0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6300: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6310: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6320: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6330: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
6340: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
6350: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
6360: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
6370: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6380: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6390: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
63a0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
63b0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
63c0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
63d0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
63e0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
63f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6400: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6410: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6420: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6430: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6440: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
6450: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6460: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
6470: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
6480: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
6490: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
64a0: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
64b0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
64c0: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
64d0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
64e0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
64f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6500: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6510: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6520: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
6530: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
6540: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
6550: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
6560: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
6570: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
6580: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
6590: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
65a0: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
65b0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
65c0: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
65d0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
65e0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
65f0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
6600: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
6610: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6620: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
6630: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
6640: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
6650: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
6660: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
6670: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
6680: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
6690: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
66a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
66b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
66c0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
66d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
66e0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
66f0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
6700: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6710: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
6720: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6730: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
6740: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
6750: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6760: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6770: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6780: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6790: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
67a0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
67b0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
67c0: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
67d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
67e0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
67f0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
6800: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
6810: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
6820: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
6830: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
6840: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
6850: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6860: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6870: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6880: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6890: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
68a0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
68b0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
68c0: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
68d0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
68e0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
68f0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
6900: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
6910: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
6920: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
6930: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
6940: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
6950: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6960: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6970: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6980: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6990: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
69a0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
69b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
69c0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
69d0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
69e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
69f0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
6a00: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
6a10: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
6a20: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6a30: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
6a40: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
6a50: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6a60: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6a70: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6a80: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6a90: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6aa0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6ab0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6ac0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6ad0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6ae0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6af0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
6b00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
6b10: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
6b20: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6b30: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
6b40: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
6b50: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
6b60: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6b70: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
6b80: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
6b90: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
6ba0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6bb0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6bc0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6bd0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6be0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6bf0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6c00: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
6c10: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
6c20: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
6c30: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6c40: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
6c50: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6c60: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
6c70: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
6c80: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6c90: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
6ca0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
6cb0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
6cc0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
6cd0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
6ce0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6cf0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6d00: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6d10: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
6d20: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6d30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6d40: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6d50: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6d60: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6d70: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6d80: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
6d90: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
6da0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
6db0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
6dc0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6dd0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
6de0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6df0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6e00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6e10: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6e20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6e30: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6e40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6e50: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6e60: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6e70: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6e80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
6e90: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
6ea0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
6eb0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6ec0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
6ed0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
6ee0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6ef0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6f00: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6f10: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6f20: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6f30: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6f40: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6f50: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6f60: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6f70: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6f80: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
6f90: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
6fa0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
6fb0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
6fc0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
6fd0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
6fe0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6ff0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
7000: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
7010: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
7020: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
7030: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7040: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
7050: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
7060: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7070: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7080: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
7090: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
70a0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
70b0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
70c0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
70d0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
70e0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
70f0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
7100: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
7110: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
7120: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
7130: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
7140: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
7150: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
7160: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
7170: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
7180: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
7190: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
71a0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
71b0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
71c0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
71d0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
71e0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
71f0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7200: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7210: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7220: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7230: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
7240: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
7250: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
7260: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
7270: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
7280: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
7290: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
72a0: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
72b0: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
72c0: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
72d0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
72e0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
72f0: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7300: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7310: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7320: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7330: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
7340: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
7350: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7360: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
7370: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
7380: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
7390: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
73a0: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
73b0: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
73c0: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
73d0: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
73e0: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
73f0: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7400: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7410: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7420: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7430: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
7440: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
7450: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
7460: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
7470: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
7480: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
7490: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
74a0: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
74b0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
74c0: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
74d0: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
74e0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
74f0: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7500: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7510: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7520: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7530: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7540: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
7550: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7560: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
7570: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7580: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
7590: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
75a0: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
75b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
75c0: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
75d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
75e0: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
75f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7600: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
7610: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7620: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
7630: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
7640: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
7650: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7660: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
7670: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
7680: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7690: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
76a0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
76b0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
76c0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
76d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
76e0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
76f0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7700: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7710: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7720: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
7730: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
7740: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
7750: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
7760: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
7770: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
7780: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7790: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
77a0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
77b0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
77c0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
77d0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
77e0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
77f0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
7800: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
7810: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
7820: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
7830: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
7840: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
7850: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
7860: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
7870: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
7880: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
7890: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
78a0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
78b0: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
78c0: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
78d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
78e0: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
78f0: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
7900: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
7910: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
7920: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
7930: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
7940: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
7950: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
7960: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
7970: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
7980: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
7990: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
79a0: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
79b0: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
79c0: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
79d0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
79e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
79f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7a00: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7a10: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7a20: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7a30: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
7a40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7a50: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
7a60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
7a70: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
7a80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
7a90: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
7aa0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7ab0: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
7ac0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7ad0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7ae0: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7af0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7b00: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7b10: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7b20: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7b30: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
7b40: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
7b50: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
7b60: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
7b70: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
7b80: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
7b90: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
7ba0: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
7bb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7bc0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
7bd0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7be0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7bf0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7c00: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7c10: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7c20: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7c30: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7c40: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7c50: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7c60: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
7c70: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
7c80: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
7c90: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7ca0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7cb0: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
7cc0: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
7cd0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
7ce0: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
7cf0: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
7d00: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
7d10: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
7d20: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
7d30: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
7d40: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
7d50: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
7d60: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7d70: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
7d80: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7d90: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
7da0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7db0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7dc0: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a  ersion 2 */.  /*
7dd0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
7de0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
7df0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
7e00: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
7e10: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
7e20: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
7e30: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
7e40: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
7e50: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
7e60: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
7e70: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
7e80: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
7e90: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7ea0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
7eb0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7ec0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
7ed0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
7ee0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7ef0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
7f00: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
7f10: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
7f20: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
7f30: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7f40: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
7f50: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
7f60: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
7f70: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
7f80: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
7f90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7fa0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
7fb0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
7fc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7fd0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
7fe0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7ff0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8000: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8010: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8020: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8030: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8040: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8050: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8060: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8070: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8080: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8090: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
80a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
80b0: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
80c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
80d0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
80e0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
80f0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8100: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8110: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8120: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8130: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8140: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8150: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8160: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8170: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8180: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8190: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
81a0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
81b0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
81c0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
81d0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
81e0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
81f0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8200: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8210: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8220: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8230: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8240: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8250: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8260: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
8270: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8280: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
8290: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
82a0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
82b0: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
82c0: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
82d0: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
82e0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
82f0: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
8300: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
8310: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
8320: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8330: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
8340: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
8350: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
8360: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
8370: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
8380: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
8390: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
83a0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
83b0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
83c0: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
83d0: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
83e0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
83f0: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
8400: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
8410: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
8420: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
8430: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
8440: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8450: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
8460: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
8470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
8480: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
8490: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
84a0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
84b0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
84c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
84d0: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
84e0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
84f0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
8500: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
8510: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8520: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
8530: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
8540: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
8550: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8560: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
8570: 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65  ITTED]].** ^(The
8580: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8590: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
85a0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
85b0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
85c0: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
85d0: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
85e0: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
85f0: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
8600: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
8610: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
8620: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
8630: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
8640: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
8650: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
8660: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
8670: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
8680: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
8690: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
86a0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
86b0: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
86c0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
86d0: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
86e0: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
86f0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
8700: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
8710: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
8720: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
8730: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
8740: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
8750: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8760: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
8770: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
8780: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
8790: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
87a0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
87b0: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
87c0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
87d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
87e0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
87f0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
8800: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
8810: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
8820: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
8830: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
8840: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
8850: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
8860: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
8870: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
8880: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
8890: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
88a0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
88b0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
88c0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
88d0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
88e0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
88f0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
8900: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
8910: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
8920: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
8930: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
8940: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
8950: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
8960: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
8970: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
8980: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
8990: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
89a0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
89b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
89c0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
89d0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
89e0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
89f0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
8a00: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
8a10: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
8a20: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
8a30: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
8a40: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
8a50: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
8a60: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
8a70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8a80: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
8a90: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
8aa0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
8ab0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
8ac0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
8ad0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
8ae0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
8af0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
8b00: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
8b10: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
8b20: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
8b30: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
8b40: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
8b50: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
8b60: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
8b70: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
8b80: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
8b90: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
8ba0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
8bb0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
8bc0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
8bd0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
8be0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
8bf0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
8c00: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
8c10: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
8c20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8c30: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
8c40: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
8c50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
8c60: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
8c70: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
8c80: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
8c90: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
8ca0: 20 57 72 69 74 65 20 41 48 65 61 64 20 4c 6f 67   Write AHead Log
8cb0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
8cc0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
8cd0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
8ce0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
8cf0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
8d00: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
8d10: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
8d20: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
8d30: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
8d40: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
8d50: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
8d60: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
8d70: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
8d80: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
8d90: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
8da0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
8db0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
8dc0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
8dd0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
8de0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
8df0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
8e00: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
8e10: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
8e20: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
8e30: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
8e40: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
8e50: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
8e60: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
8e70: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
8e80: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
8e90: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
8ea0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
8eb0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
8ec0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
8ed0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
8ee0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8ef0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
8f00: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
8f10: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
8f20: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
8f30: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
8f40: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
8f50: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
8f60: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
8f70: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
8f80: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
8f90: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
8fa0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
8fb0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
8fc0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
8fd0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
8fe0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8ff0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9000: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9010: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9020: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9030: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9040: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9050: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9060: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9070: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9080: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9090: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
90a0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
90b0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
90c0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
90d0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
90e0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
90f0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9100: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9110: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
9120: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9130: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
9140: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
9150: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
9160: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
9170: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
9180: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
9190: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
91a0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
91b0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
91c0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
91d0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
91e0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
91f0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9200: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
9210: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
9220: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9230: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
9240: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
9250: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9260: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9270: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
9280: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
9290: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
92a0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
92b0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
92c0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
92d0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
92e0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
92f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9300: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
9310: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
9320: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
9330: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
9340: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
9350: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
9360: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9370: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
9380: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9390: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
93a0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
93b0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
93c0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
93d0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
93e0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
93f0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
9400: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
9410: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
9420: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
9430: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
9440: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
9450: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
9460: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
9470: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
9480: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
9490: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
94a0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
94b0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
94c0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
94d0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
94e0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
94f0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
9500: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
9510: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
9520: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
9530: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
9540: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
9550: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
9560: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
9570: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
9580: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
9590: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
95a0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
95b0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
95c0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
95d0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
95e0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
95f0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
9600: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
9610: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
9620: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
9630: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9640: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
9650: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
9660: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
9670: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
9680: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
9690: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
96a0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
96b0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
96c0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
96d0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
96e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
96f0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
9700: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
9710: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
9720: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
9730: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
9740: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
9750: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
9760: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
9770: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
9780: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
9790: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
97a0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
97b0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
97c0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
97d0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
97e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
97f0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
9800: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
9810: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
9820: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
9830: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
9840: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
9850: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
9860: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
9870: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
9880: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
9890: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
98a0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
98b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
98c0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
98d0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
98e0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
98f0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
9900: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
9910: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
9920: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
9930: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
9940: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
9950: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
9960: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
9970: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
9980: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
9990: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
99a0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
99b0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
99c0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
99d0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
99e0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
99f0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
9a00: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
9a10: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
9a20: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
9a30: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
9a40: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
9a50: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
9a60: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
9a70: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
9a80: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
9a90: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9aa0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
9ab0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
9ac0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
9ad0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
9ae0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
9af0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
9b00: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
9b10: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
9b20: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
9b30: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
9b40: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
9b50: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
9b60: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
9b70: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
9b80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9b90: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
9ba0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
9bb0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
9bc0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
9bd0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
9be0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
9bf0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
9c00: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
9c10: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c  statements..** <
9c20: 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /ul>.*/.#define 
9c30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
9c40: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20  KSTATE          
9c50: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
9c60: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
9c70: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
9c80: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
9c90: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
9ca0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20  XYFILE          
9cb0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
9cc0: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  ITE_LAST_ERRNO  
9cd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
9ce0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
9cf0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
9d00: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
9d10: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
9d20: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9d30: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
9d40: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
9d50: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9d60: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37  TER            7
9d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9d80: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
9d90: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a  ED            8.
9da0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
9db0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9dc0: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23  TRY          9.#
9dd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
9de0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
9df0: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
9e00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
9e10: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
9e20: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
9e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
9e40: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20  L_VFSNAME       
9e50: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
9e60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
9e70: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9e80: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69  RITE    13.#defi
9e90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
9ea0: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
9eb0: 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a         14../*.**
9ec0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
9ed0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
9ee0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
9ef0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
9f00: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
9f10: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
9f20: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
9f30: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
9f40: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
9f50: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
9f60: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
9f70: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
9f80: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
9f90: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
9fa0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
9fb0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
9fc0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
9fd0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
9fe0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
9ff0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
a000: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
a010: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
a020: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
a030: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
a040: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a050: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
a060: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
a070: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
a080: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
a090: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
a0a0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
a0b0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
a0c0: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
a0d0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
a0e0: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
a0f0: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
a100: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
a110: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
a120: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
a130: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
a140: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
a150: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
a160: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
a170: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
a180: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
a190: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
a1a0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
a1b0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
a1c0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
a1d0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
a1e0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
a1f0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
a200: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
a210: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
a220: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
a230: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
a240: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
a250: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
a260: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
a270: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
a280: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
a290: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
a2a0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
a2b0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
a2c0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
a2d0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
a2e0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
a2f0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
a300: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
a310: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
a320: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
a330: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
a340: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
a350: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
a360: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
a370: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
a380: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
a390: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
a3a0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
a3b0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
a3c0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
a3d0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
a3e0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
a3f0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
a400: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
a410: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
a420: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
a430: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
a440: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
a450: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
a460: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
a470: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
a480: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
a490: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
a4a0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
a4b0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
a4c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
a4d0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
a4e0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
a4f0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
a500: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
a510: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
a520: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
a530: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
a540: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
a550: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
a560: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
a570: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
a580: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
a590: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
a5a0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
a5b0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
a5c0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
a5d0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
a5e0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
a5f0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
a600: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
a610: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
a620: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
a630: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
a640: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
a650: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
a660: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
a670: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
a680: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
a690: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
a6a0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
a6b0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
a6c0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
a6d0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
a6e0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
a6f0: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
a700: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
a710: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
a720: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
a730: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
a740: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
a750: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
a760: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
a770: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
a780: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
a790: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
a7a0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
a7b0: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
a7c0: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
a7d0: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
a7e0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
a7f0: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
a800: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
a810: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
a820: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
a830: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
a840: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
a850: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
a860: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
a870: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
a880: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
a890: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
a8a0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
a8b0: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
a8c0: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
a8d0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
a8e0: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
a8f0: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
a900: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
a910: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
a920: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
a930: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
a940: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
a950: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
a960: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
a970: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
a980: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
a990: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
a9a0: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
a9b0: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
a9c0: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
a9d0: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
a9e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
a9f0: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
aa00: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
aa10: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
aa20: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
aa30: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
aa40: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
aa50: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
aa60: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
aa70: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
aa80: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
aa90: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
aaa0: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
aab0: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
aac0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
aad0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
aae0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
aaf0: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
ab00: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
ab10: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
ab20: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
ab30: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
ab40: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
ab50: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
ab60: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
ab70: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
ab80: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
ab90: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
aba0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
abb0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
abc0: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
abd0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
abe0: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
abf0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ac00: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ac10: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
ac20: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ac30: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
ac40: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ac50: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
ac60: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ac70: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
ac80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
ac90: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
aca0: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
acb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
acc0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
acd0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
ace0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
acf0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ad00: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
ad10: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
ad20: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
ad30: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
ad40: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
ad50: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
ad60: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
ad70: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
ad80: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
ad90: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
ada0: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
adb0: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
adc0: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
add0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
ade0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
adf0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
ae00: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
ae10: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
ae20: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
ae30: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
ae40: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
ae50: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
ae60: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
ae70: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
ae80: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
ae90: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
aea0: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
aeb0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
aec0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
aed0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
aee0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
aef0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
af00: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
af10: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
af20: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
af30: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
af40: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
af50: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
af60: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
af70: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
af80: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
af90: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
afa0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
afb0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
afc0: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
afd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
afe0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
aff0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
b000: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
b010: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
b020: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
b030: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
b040: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
b050: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
b060: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
b070: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
b080: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
b090: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
b0a0: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
b0b0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
b0c0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
b0d0: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
b0e0: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
b0f0: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
b100: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
b110: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
b120: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
b130: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
b140: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
b150: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
b160: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
b170: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
b180: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
b190: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
b1a0: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
b1b0: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
b1c0: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
b1d0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
b1e0: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
b1f0: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
b200: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
b210: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
b220: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
b230: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
b240: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
b250: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
b260: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
b270: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
b280: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
b290: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
b2a0: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
b2b0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
b2c0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
b2d0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
b2e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
b2f0: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
b300: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
b310: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
b320: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
b330: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
b340: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
b350: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
b360: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
b370: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
b380: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
b390: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
b3a0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
b3b0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
b3c0: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
b3d0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
b3e0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
b3f0: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
b400: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
b410: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
b420: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
b430: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
b440: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
b450: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
b460: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
b470: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
b480: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
b490: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
b4a0: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
b4b0: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
b4c0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
b4d0: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
b4e0: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
b4f0: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
b500: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
b510: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
b520: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
b530: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
b540: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
b550: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
b560: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
b570: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
b580: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
b590: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
b5a0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
b5b0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
b5c0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
b5d0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
b5e0: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
b5f0: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
b600: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
b610: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
b620: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
b630: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
b640: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
b650: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
b660: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
b670: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
b680: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
b690: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
b6a0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
b6b0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
b6c0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
b6d0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
b6e0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
b6f0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
b700: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
b710: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
b720: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
b730: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
b740: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
b750: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
b760: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
b770: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
b780: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
b790: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
b7a0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
b7b0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
b7c0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
b7d0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
b7e0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
b7f0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
b800: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
b810: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
b820: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
b830: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
b840: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
b850: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
b860: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
b870: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
b880: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
b890: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
b8a0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
b8b0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
b8c0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
b8d0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
b8e0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
b8f0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
b900: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
b910: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
b920: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
b930: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
b940: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
b950: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
b960: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
b970: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
b980: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
b990: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
b9a0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
b9b0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
b9c0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
b9d0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
b9e0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
b9f0: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
ba00: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
ba10: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
ba20: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
ba30: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
ba40: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
ba50: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
ba60: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
ba70: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
ba80: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
ba90: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
baa0: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
bab0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
bac0: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
bad0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
bae0: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
baf0: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
bb00: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
bb10: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
bb20: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
bb30: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
bb40: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
bb50: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
bb60: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
bb70: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
bb80: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
bb90: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
bba0: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
bbb0: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
bbc0: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
bbd0: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
bbe0: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
bbf0: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
bc00: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
bc10: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
bc20: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
bc30: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
bc40: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
bc50: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
bc60: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
bc70: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
bc80: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
bc90: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
bca0: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
bcb0: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
bcc0: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
bcd0: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
bce0: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
bcf0: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
bd00: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
bd10: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
bd20: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
bd30: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
bd40: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
bd50: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
bd60: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
bd70: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
bd80: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
bd90: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
bda0: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
bdb0: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
bdc0: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
bdd0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
bde0: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
bdf0: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
be00: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
be10: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
be20: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
be30: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
be40: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
be50: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
be60: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
be70: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
be80: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
be90: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
bea0: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
beb0: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
bec0: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
bed0: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
bee0: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
bef0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
bf00: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
bf10: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
bf20: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
bf30: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
bf40: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
bf50: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
bf60: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
bf70: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
bf80: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
bf90: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
bfa0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
bfb0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
bfc0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
bfd0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
bfe0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
bff0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
c000: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
c010: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
c020: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
c030: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
c040: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
c050: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
c060: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
c070: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
c080: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
c090: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
c0a0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
c0b0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
c0c0: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
c0d0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
c0e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c0f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
c100: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
c110: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
c120: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
c130: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
c140: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
c150: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
c160: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
c170: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
c180: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
c190: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
c1a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
c1b0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
c1c0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
c1d0: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
c1e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
c1f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
c200: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
c210: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
c220: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
c230: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c240: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
c250: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
c260: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
c270: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
c280: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
c290: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
c2a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
c2b0: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
c2c0: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
c2d0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
c2e0: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
c2f0: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
c300: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
c310: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
c320: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
c330: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
c340: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
c350: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
c360: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
c370: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
c380: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
c390: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
c3a0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
c3b0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
c3c0: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
c3d0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
c3e0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
c3f0: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
c400: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
c410: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
c420: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
c430: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
c440: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
c450: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
c460: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
c470: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
c480: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
c490: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
c4a0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
c4b0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
c4c0: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
c4d0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
c4e0: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
c4f0: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
c500: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
c510: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
c520: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
c530: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c540: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
c550: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
c560: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
c570: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
c580: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
c590: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
c5a0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
c5b0: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
c5c0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
c5d0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c5e0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
c5f0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
c600: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
c610: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
c620: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
c630: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
c640: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
c650: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
c660: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
c670: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
c680: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
c690: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
c6a0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
c6b0: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
c6c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
c6d0: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
c6e0: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
c6f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
c700: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
c710: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
c720: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
c730: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
c740: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
c750: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
c760: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
c770: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
c780: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
c790: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
c7a0: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
c7b0: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
c7c0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
c7d0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
c7e0: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
c7f0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
c800: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
c810: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
c820: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
c830: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
c840: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
c850: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
c860: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
c870: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
c880: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
c890: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
c8a0: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
c8b0: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
c8c0: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
c8d0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
c8e0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
c8f0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
c900: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
c910: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
c920: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
c930: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
c940: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
c950: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
c960: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
c970: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
c980: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
c990: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
c9a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
c9b0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
c9c0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
c9d0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
c9e0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
c9f0: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
ca00: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
ca10: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
ca20: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
ca30: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
ca40: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
ca50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ca60: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
ca70: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
ca80: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
ca90: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
caa0: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
cab0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
cac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cad0: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
cae0: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
caf0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
cb00: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
cb10: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
cb20: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
cb30: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
cb40: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
cb50: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
cb60: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
cb70: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
cb80: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
cb90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
cba0: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
cbb0: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
cbc0: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
cbd0: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
cbe0: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
cbf0: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
cc00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
cc10: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
cc20: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
cc30: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
cc40: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
cc50: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
cc60: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
cc70: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
cc80: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
cc90: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
cca0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
ccb0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
ccc0: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
ccd0: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
cce0: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
ccf0: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
cd00: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
cd10: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
cd20: 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72  iven no the corr
cd30: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
cd40: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
cd50: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
cd60: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
cd70: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
cd80: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
cd90: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
cda0: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
cdb0: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
cdc0: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
cdd0: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
cde0: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
cdf0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
ce00: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
ce10: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
ce20: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
ce30: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
ce40: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
ce50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
ce60: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
ce70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ce80: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
ce90: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
cea0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
ceb0: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
cec0: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
ced0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
cee0: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
cef0: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
cf00: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
cf10: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
cf20: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
cf30: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
cf40: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
cf50: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
cf60: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
cf70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cf80: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
cf90: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
cfa0: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
cfb0: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
cfc0: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
cfd0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
cfe0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
cff0: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
d000: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
d010: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
d020: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
d030: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
d040: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
d050: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
d060: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
d070: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
d080: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
d090: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
d0a0: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
d0b0: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
d0c0: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
d0d0: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
d0e0: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
d0f0: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
d100: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
d110: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
d120: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
d130: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
d140: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
d150: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
d160: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
d170: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
d180: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
d190: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
d1a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
d1b0: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
d1c0: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
d1d0: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
d1e0: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
d1f0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
d200: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d210: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
d220: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
d230: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
d240: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
d250: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
d260: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
d270: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
d280: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
d290: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
d2a0: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
d2b0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
d2c0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
d2d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d2e0: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
d2f0: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
d300: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
d310: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
d320: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
d330: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
d340: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
d350: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
d360: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
d370: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d380: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
d390: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
d3a0: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
d3b0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
d3c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
d3d0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
d3e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
d3f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d400: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
d410: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
d420: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d430: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
d440: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
d450: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
d460: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
d470: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
d480: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
d490: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
d4a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
d4b0: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
d4c0: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
d4d0: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
d4e0: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
d4f0: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
d500: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
d510: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
d520: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
d530: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
d540: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
d550: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
d560: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
d570: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
d580: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
d590: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
d5a0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
d5b0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
d5c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
d5d0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
d5e0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
d5f0: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
d600: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
d610: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d620: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
d630: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
d640: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
d650: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
d660: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
d670: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
d680: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
d690: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
d6a0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
d6b0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
d6c0: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
d6d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d6e0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
d6f0: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
d700: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
d710: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
d720: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
d730: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
d740: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
d750: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
d760: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d770: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
d780: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
d790: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
d7a0: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
d7b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
d7c0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
d7d0: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
d7e0: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
d7f0: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
d800: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
d810: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
d820: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
d830: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
d840: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
d850: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
d860: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
d870: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
d880: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
d890: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
d8a0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
d8b0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
d8c0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
d8d0: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
d8e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
d8f0: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
d900: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
d910: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
d920: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
d930: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
d940: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
d950: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
d960: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
d970: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
d980: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
d990: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
d9a0: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
d9b0: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
d9c0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
d9d0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
d9e0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
d9f0: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
da00: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
da10: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
da20: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
da30: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
da40: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
da50: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
da60: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
da70: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
da80: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
da90: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
daa0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
dab0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
dac0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
dad0: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
dae0: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
daf0: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
db00: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
db10: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
db20: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
db30: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
db40: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
db50: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
db60: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
db70: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
db80: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
db90: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
dba0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
dbb0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
dbc0: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
dbd0: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
dbe0: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
dbf0: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
dc00: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
dc10: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
dc20: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
dc30: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
dc40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
dc50: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
dc60: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
dc70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
dc80: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
dc90: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
dca0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
dcb0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
dcc0: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
dcd0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
dce0: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
dcf0: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
dd00: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
dd10: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
dd20: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
dd30: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
dd40: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
dd50: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
dd60: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
dd70: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
dd80: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
dd90: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
dda0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
ddb0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
ddc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
ddd0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
dde0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
ddf0: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
de00: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
de10: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
de20: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
de30: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
de40: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
de50: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
de60: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
de70: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
de80: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
de90: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
dea0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
deb0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
dec0: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
ded0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
dee0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
def0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
df00: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
df10: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
df20: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
df30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
df40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
df50: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
df60: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
df70: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
df80: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
df90: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
dfa0: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
dfb0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
dfc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
dfd0: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
dfe0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dff0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
e000: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
e010: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
e020: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
e030: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
e040: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
e050: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
e060: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
e070: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
e080: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
e090: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
e0a0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
e0b0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
e0c0: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
e0d0: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
e0e0: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
e0f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
e100: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
e110: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
e120: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
e130: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
e140: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
e150: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
e160: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
e170: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
e180: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
e190: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
e1a0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
e1b0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
e1c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
e1d0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
e1e0: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
e1f0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
e200: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
e210: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
e220: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
e230: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
e240: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
e250: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
e260: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
e270: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
e280: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
e290: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
e2a0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
e2b0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
e2c0: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
e2d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e2e0: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
e2f0: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
e300: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
e310: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
e320: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
e330: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
e340: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
e350: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
e360: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e370: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
e380: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
e390: 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
e3a0: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
e3b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
e3c0: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
e3d0: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
e3e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
e3f0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
e400: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
e410: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
e420: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
e430: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
e440: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
e450: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
e460: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
e470: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
e480: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
e490: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
e4a0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
e4b0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
e4c0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
e4d0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
e4e0: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
e4f0: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
e500: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e510: 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
e520: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
e530: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
e540: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
e550: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
e560: 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
e570: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
e580: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
e590: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
e5a0: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
e5b0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
e5c0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
e5d0: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
e5e0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
e5f0: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
e600: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
e610: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
e620: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
e630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
e640: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
e650: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
e660: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
e670: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
e680: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
e690: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
e6a0: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
e6b0: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
e6c0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
e6d0: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
e6e0: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
e6f0: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
e700: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
e710: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
e720: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e730: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
e740: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
e750: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
e760: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
e770: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
e780: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
e790: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
e7a0: 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
e7b0: 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
e7c0: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
e7d0: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
e7e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e7f0: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
e800: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
e810: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
e820: 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
e830: 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
e840: 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
e850: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
e860: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
e870: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
e880: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
e890: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
e8a0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
e8b0: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
e8c0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
e8d0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
e8e0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
e8f0: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
e900: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
e910: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
e920: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
e930: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
e940: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
e950: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
e960: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
e970: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
e980: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
e990: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
e9a0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
e9b0: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
e9c0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
e9d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
e9e0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
e9f0: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
ea00: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
ea10: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
ea20: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
ea30: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
ea40: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
ea50: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
ea60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
ea70: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
ea80: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
ea90: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
eaa0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
eab0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
eac0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
ead0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
eae0: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
eaf0: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
eb00: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
eb10: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
eb20: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
eb30: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
eb40: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
eb50: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
eb60: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
eb70: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
eb80: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
eb90: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
eba0: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
ebb0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
ebc0: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
ebd0: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
ebe0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
ebf0: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
ec00: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
ec10: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
ec20: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
ec30: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
ec40: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
ec50: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
ec60: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
ec70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ec80: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
ec90: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
eca0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
ecb0: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
ecc0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
ecd0: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
ece0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
ecf0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
ed00: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
ed10: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
ed20: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
ed30: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
ed40: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
ed50: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
ed60: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
ed70: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
ed80: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
ed90: 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
eda0: 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
edb0: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
edc0: 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
edd0: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
ede0: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
edf0: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
ee00: 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
ee10: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
ee20: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
ee30: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
ee40: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
ee50: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
ee60: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
ee70: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
ee80: 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
ee90: 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
eea0: 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
eeb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
eec0: 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
eed0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
eee0: 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
eef0: 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
ef00: 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
ef10: 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
ef20: 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
ef30: 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
ef40: 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
ef50: 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
ef60: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
ef70: 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
ef80: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
ef90: 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
efa0: 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
efb0: 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
efc0: 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
efd0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
efe0: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
eff0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f000: 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
f010: 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
f020: 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
f030: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
f040: 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
f050: 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
f060: 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
f070: 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
f080: 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
f090: 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
f0a0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
f0b0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
f0c0: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
f0d0: 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
f0e0: 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
f0f0: 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
f100: 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
f110: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
f120: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f130: 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
f140: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
f150: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
f160: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
f170: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .  (For example,
f180: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
f190: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
f1a0: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
f1b0: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
f1c0: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
f1d0: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
f1e0: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
f1f0: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
f200: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
f210: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
f220: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
f230: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
f240: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
f250: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
f260: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
f270: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
f280: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
f290: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
f2a0: 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
f2b0: 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
f2c0: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
f2d0: 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
f2e0: 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
f2f0: 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
f300: 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
f310: 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
f320: 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
f330: 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
f340: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
f350: 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
f360: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f370: 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
f380: 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
f390: 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
f3a0: 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
f3b0: 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
f3c0: 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
f3d0: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
f3e0: 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
f3f0: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
f400: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
f410: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
f420: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f430: 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
f440: 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
f450: 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
f460: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
f470: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
f480: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
f490: 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
f4a0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
f4b0: 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
f4c0: 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
f4d0: 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
f4e0: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
f4f0: 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
f500: 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
f510: 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
f520: 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
f530: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
f540: 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
f550: 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
f560: 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
f570: 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
f580: 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
f590: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
f5a0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f5b0: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
f5c0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
f5d0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f5e0: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
f5f0: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
f600: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
f610: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
f620: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
f630: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
f640: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
f650: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
f660: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
f670: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
f680: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
f690: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
f6a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
f6b0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
f6c0: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
f6d0: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
f6e0: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
f6f0: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
f700: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
f710: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
f720: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
f730: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
f740: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
f750: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
f760: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
f770: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
f780: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
f790: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
f7a0: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
f7b0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
f7c0: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
f7d0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
f7e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
f7f0: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
f800: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
f810: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
f820: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
f830: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
f840: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
f850: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f860: 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
f870: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
f880: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
f890: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
f8a0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
f8b0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
f8c0: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
f8d0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
f8e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
f8f0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
f900: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
f910: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
f920: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
f930: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
f940: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
f950: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f960: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
f970: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
f980: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
f990: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
f9a0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
f9b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f9c0: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
f9d0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
f9e0: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
f9f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fa00: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
fa10: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
fa20: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
fa30: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
fa40: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
fa50: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
fa60: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
fa70: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
fa80: 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
fa90: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
faa0: 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
fab0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
fac0: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
fad0: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
fae0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
faf0: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
fb00: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
fb10: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
fb20: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
fb30: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
fb40: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
fb50: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
fb60: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
fb70: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
fb80: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
fb90: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
fba0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
fbb0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
fbc0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
fbd0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
fbe0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
fbf0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
fc00: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
fc10: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
fc20: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
fc30: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
fc40: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
fc50: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
fc60: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
fc70: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
fc80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
fc90: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
fca0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
fcb0: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
fcc0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
fcd0: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
fce0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fcf0: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
fd00: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
fd10: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
fd20: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fd30: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
fd40: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
fd50: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
fd60: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
fd70: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
fd80: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
fd90: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
fda0: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
fdb0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
fdc0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
fdd0: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
fde0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
fdf0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
fe00: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
fe10: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
fe20: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
fe30: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
fe40: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
fe50: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fe60: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
fe70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
fe80: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
fe90: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
fea0: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
feb0: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
fec0: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
fed0: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
fee0: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
fef0: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
ff00: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
ff10: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
ff20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ff30: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
ff40: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
ff50: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
ff60: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
ff70: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
ff80: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
ff90: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
ffa0: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
ffb0: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
ffc0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
ffd0: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
ffe0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
fff0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10000 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
10010 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
10020 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
10030 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
10040 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
10050 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10060 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
10070 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10080 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
10090 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
100a0 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
100b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
100c0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
100d0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
100e0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
100f0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
10100 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
10110 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
10120 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
10130 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
10140 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
10150 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
10160 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
10170 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
10180 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
10190 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
101a0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
101b0 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
101c0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
101d0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
101e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
101f0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
10200 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
10210 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
10220 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
10230 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
10240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10250 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
10260 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
10270 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
10280 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
10290 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
102a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
102b0 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
102c0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
102d0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
102e0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
102f0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
10300 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
10310 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
10320 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
10330 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
10340 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
10350 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
10360 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
10370 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
10380 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
10390 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
103a0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
103b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
103c0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
103d0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
103e0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
103f0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
10400 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
10410 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10420 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
10430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10440 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
10450 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
10460 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
10470 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10480 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
10490 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
104a0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
104b0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
104c0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
104d0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
104e0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
104f0 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
10500 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
10510 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10520 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  n routines to be
10530 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f   used in place o
10540 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  f.** the memory 
10550 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
10560 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
10570 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65  QLite.)^ ^SQLite
10580 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77   makes.** its ow
10590 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
105a0 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  f the content of
105b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
105c0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
105d0 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ture.** before t
105e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
105f0 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72  ig()] call retur
10600 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
10610 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
10620 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  ETMALLOC]] <dt>S
10630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
10640 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
10650 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
10660 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
10670 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
10680 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
10690 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
106a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
106b0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
106c0 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
106d0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
106e0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
106f0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
10700 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
10710 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
10720 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
10730 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
10740 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
10750 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
10760 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
10770 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
10780 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
10790 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
107a0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
107b0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
107c0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
107d0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
107e0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
107f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10800 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
10810 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
10820 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
10830 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
10840 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
10850 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
10860 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
10870 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65  d as a .** boole
10880 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
10890 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
108a0 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20  e collection of 
108b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
108c0 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73  n .** statistics
108d0 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
108e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
108f0 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
10900 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c  ed, the .** foll
10910 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
10920 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
10930 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
10940 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
10950 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
10960 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
10970 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
10980 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
10990 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
109a0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
109b0 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
109c0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
109d0 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
109e0 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
109f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
10a00 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
10a10 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
10a20 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
10a30 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
10a40 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
10a50 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
10a60 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
10a70 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
10a80 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
10a90 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
10aa0 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
10ab0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10ac0 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
10ad0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
10ae0 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
10af0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
10b00 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
10b10 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
10b20 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
10b30 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
10b40 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
10b50 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
10b60 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
10b70 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
10b80 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
10b90 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
10ba0 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c   the scratch all
10bb0 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  ocations will be
10bc0 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73  .** drawn, the s
10bd0 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
10be0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  tch allocation (
10bf0 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
10c00 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
10c10 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  f scratch alloca
10c20 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20  tions (N).  The 
10c30 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  sz.** argument m
10c40 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c  ust be a multipl
10c50 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20  e of 16..** The 
10c60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
10c70 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
10c80 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
10c90 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
10ca0 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
10cb0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
10cc0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
10cd0 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68  l use no more th
10ce0 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62  an two scratch b
10cf0 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
10d00 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75  d.  So.** N shou
10d10 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69  ld be set to twi
10d20 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20  ce the expected 
10d30 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
10d40 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53  f threads..** ^S
10d50 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
10d60 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74   require a scrat
10d70 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
10d80 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
10d90 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
10da0 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e  ase page size. ^
10db0 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
10dc0 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
10dd0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
10de0 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
10df0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
10e00 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
10e10 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a   option, then .*
10e20 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
10e30 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65  c()] will be use
10e40 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
10e50 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f  memory needed.</
10e60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10e70 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
10e80 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
10e90 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
10ea0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
10eb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
10ec0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
10ed0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
10ee0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
10ef0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
10f00 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
10f10 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
10f20 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
10f30 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
10f40 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
10f50 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  ion should not b
10f60 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70  e used if an app
10f70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
10f80 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
10f90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
10fa0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
10fb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
10fc0 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a  CACHE2 option..*
10fd0 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
10fe0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
10ff0 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f  his option: A po
11000 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20  inter to 8-byte 
11010 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72  aligned.** memor
11020 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
11030 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
11040 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
11050 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
11060 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
11070 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
11080 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
11090 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
110a0 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
110b0 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
110c0 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20   512 and 32768) 
110d0 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78  plus a little ex
110e0 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tra for each.** 
110f0 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
11100 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
11110 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
11120 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
11130 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
11140 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49  rchitecture.  ^I
11150 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
11160 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
11170 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
11180 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
11190 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
111a0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
111b0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
111c0 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
111d0 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
111e0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
111f0 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
11200 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
11210 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
11220 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11230 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
11240 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
11250 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
11260 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
11270 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
11280 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
11290 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
112a0 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
112b0 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
112c0 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
112d0 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
112e0 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
112f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11300 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
11310 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
11320 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  e..** The pointe
11330 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
11340 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20  rgument must.** 
11350 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
11360 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
11370 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
11380 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
11390 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64  e.** will be und
113a0 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
113b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
113c0 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
113d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
113e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
113f0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
11400 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
11410 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
11420 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
11430 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
11440 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
11450 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
11460 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
11470 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
11480 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
11490 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
114a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
114b0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
114c0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
114d0 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
114e0 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
114f0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
11500 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
11510 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
11520 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
11530 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
11540 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
11550 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
11560 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
11570 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
11580 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
11590 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
115a0 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
115b0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
115c0 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
115d0 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
115e0 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
115f0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
11600 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
11610 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
11620 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
11630 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
11640 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
11650 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
11660 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
11670 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
11680 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
11690 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
116a0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
116b0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
116c0 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
116d0 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
116e0 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
116f0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
11700 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
11710 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
11720 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
11730 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
11740 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
11750 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
11760 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
11770 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
11780 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
11790 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
117a0 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
117b0 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
117c0 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
117d0 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
117e0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
117f0 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
11800 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
11810 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11820 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
11830 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
11840 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
11850 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11860 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
11870 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
11880 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
11890 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
118a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
118b0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
118c0 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
118d0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
118e0 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
118f0 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
11900 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
11910 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74  place.** the mut
11920 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
11930 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
11940 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
11950 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
11960 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
11970 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
11980 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
11990 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
119a0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
119b0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
119c0 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
119d0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
119e0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
119f0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11a00 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11a10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11a20 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
11a30 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
11a40 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
11a50 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
11a60 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
11a70 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
11a80 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
11a90 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
11aa0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
11ab0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11ac0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
11ad0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
11ae0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11af0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
11b00 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
11b10 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
11b20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
11b30 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11b40 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
11b50 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
11b60 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
11b70 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
11b80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
11b90 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
11ba0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
11bb0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
11bc0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
11bd0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
11be0 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
11bf0 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
11c00 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
11c10 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
11c20 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
11c30 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
11c40 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
11c50 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
11c60 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
11c70 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
11c80 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
11c90 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
11ca0 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
11cb0 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
11cc0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11cd0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11ce0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11cf0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11d00 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11d10 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11d20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
11d30 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
11d40 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
11d50 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
11d60 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
11d70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11d80 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
11d90 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
11da0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11db0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
11dc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
11dd0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
11de0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11df0 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
11e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
11e10 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
11e20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
11e30 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
11e40 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
11e50 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
11e60 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
11e70 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
11e80 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
11e90 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
11ea0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
11eb0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
11ec0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11ed0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
11ee0 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
11ef0 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
11f00 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
11f10 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
11f20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
11f30 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
11f40 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
11f50 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
11f60 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
11f70 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
11f80 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
11f90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
11fa0 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
11fb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
11fc0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
11fd0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
11fe0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
11ff0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12000 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
12010 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
12020 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12030 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
12040 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12050 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
12060 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
12070 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
12080 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
12090 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
120a0 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69  r to.** an [sqli
120b0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
120c0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
120d0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
120e0 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ies the interfac
120f0 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d  e.** to a custom
12100 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
12110 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e  ementation.)^  ^
12120 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
12130 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62  opy of the.** ob
12140 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74  ject and uses it
12150 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
12160 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12170 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
12180 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
12190 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
121a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
121b0 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
121c0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
121d0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
121e0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
121f0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
12200 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
12210 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
12220 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74  ] object.  SQLit
12230 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20  e copies of the 
12240 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20  current.** page 
12250 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12260 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f  tion into that o
12270 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  bject.)^ </dd>.*
12280 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12290 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53  NFIG_LOG]] <dt>S
122a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
122b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
122c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
122d0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
122e0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
122f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
12300 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
12310 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
12320 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
12330 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
12340 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
12350 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
12360 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
12370 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
12380 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
12390 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
123a0 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
123b0 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
123c0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
123d0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
123e0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
123f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
12400 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
12410 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
12420 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
12430 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
12440 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
12450 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
12460 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
12470 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
12480 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
12490 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
124a0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
124b0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
124c0 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
124d0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
124e0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
124f0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
12500 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
12510 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
12520 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
12530 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
12540 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
12550 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
12560 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
12570 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
12580 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
12590 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
125a0 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
125b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
125c0 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
125d0 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
125e0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
125f0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
12600 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
12610 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
12620 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
12630 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
12640 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
12650 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
12660 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
12670 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
12680 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
12690 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
126a0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
126b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
126c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
126d0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
126e0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
126f0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
12700 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12710 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
12720 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12730 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69  _URI.** <dd> Thi
12740 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
12750 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12760 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66   of type int. If
12770 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a   non-zero, then.
12780 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  ** URI handling 
12790 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
127a0 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
127b0 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74  meter is zero, t
127c0 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
127d0 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  .** is globally 
127e0 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49  disabled. If URI
127f0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
12800 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61  bally enabled, a
12810 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  ll filenames.** 
12820 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
12830 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
12840 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
12850 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
12860 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
12870 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
12880 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
12890 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
128a0 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
128b0 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
128c0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
128d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
128e0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
128f0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
12900 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
12910 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20  pened. If it is 
12920 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
12930 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
12940 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
12950 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
12960 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
12970 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
12980 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
12990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
129a0 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65  is opened. By de
129b0 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
129c0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
129d0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
129e0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
129f0 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
12a00 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
12a10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
12a20 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
12a30 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efined..**.** [[
12a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12a50 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
12a60 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
12a70 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
12a80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
12a90 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
12aa0 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
12ab0 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
12ac0 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
12ad0 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
12ae0 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
12af0 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
12b00 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
12b10 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
12b20 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
12b30 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  o-ops..** </dl>.
12b40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12b50 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
12b60 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
12b70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12b80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
12b90 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
12ba0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
12bb0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
12bc0 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
12bd0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
12be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12bf0 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
12c00 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12c10 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
12c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12c30 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
12c40 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
12c50 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
12c60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12c70 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
12c80 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
12c90 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
12ca0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12cb0 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
12cc0 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
12cd0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
12ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12cf0 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
12d00 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
12d10 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
12d20 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
12d30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12d40 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
12d50 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
12d60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12d70 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
12d80 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
12d90 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
12da0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12db0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
12dc0 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
12dd0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
12de0 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
12df0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
12e00 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
12e10 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
12e20 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
12e30 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
12e40 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
12e50 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
12e60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12e70 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
12e80 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
12e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12ea0 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
12eb0 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
12ec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12ed0 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
12ee0 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
12ef0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
12f00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12f10 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
12f20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
12f30 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12f40 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
12f50 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
12f60 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
12f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12f80 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
12f90 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
12fa0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
12fb0 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  s2* */../*.** CA
12fc0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
12fd0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66   Connection Conf
12fe0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
12ff0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
13000 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
13010 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
13020 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
13030 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
13040 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
13050 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
13060 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
13070 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
13080 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
13090 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
130a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
130b0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
130c0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
130d0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
130e0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
130f0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
13100 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
13110 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
13120 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
13130 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
13140 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
13150 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
13160 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
13170 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
13180 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64   ^The [sqlite3_d
13190 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
131a0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
131b0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
131c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
131d0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
131e0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
131f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13200 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
13210 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
13220 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
13230 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
13240 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
13250 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
13260 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
13270 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
13280 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
13290 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
132a0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
132b0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
132c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
132d0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68  nection]..** ^Th
132e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
132f0 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
13300 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
13310 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
13320 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
13330 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
13340 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
13350 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a  kaside memory..*
13360 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
13370 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20  ument after the 
13380 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
13390 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a  LOOKASIDE verb.*
133a0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  * may be NULL in
133b0 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
133c0 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
133d0 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64   the.** lookasid
133e0 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  e buffer itself 
133f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
13400 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73  alloc()]. ^The s
13410 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
13420 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
13430 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
13440 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54  buffer slot.  ^T
13450 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
13460 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
13470 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
13480 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
13490 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
134a0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
134b0 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
134c0 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
134d0 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
134e0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
134f0 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  rd arguments.  T
13500 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73  he buffer.** mus
13510 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
13520 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
13530 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63  ry.  ^If the sec
13540 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
13550 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ** SQLITE_DBCONF
13560 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20  IG_LOOKASIDE is 
13570 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f  not a multiple o
13580 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72  f 8, it is inter
13590 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64  nally.** rounded
135a0 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78   down to the nex
135b0 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70  t smaller multip
135c0 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20  le of 8.  ^(The 
135d0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
135e0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
135f0 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  n for a database
13600 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20   connection can 
13610 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20  only be changed 
13620 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e  when that.** con
13630 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63  nection is not c
13640 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c  urrently using l
13650 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c  ookaside memory,
13660 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72   or in other wor
13670 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22  ds.** when the "
13680 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72  current value" r
13690 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
136a0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73  qlite3_db_status
136b0 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ](D,[SQLITE_CONF
136c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e  IG_LOOKASIDE],..
136d0 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41  .) is zero..** A
136e0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68  ny attempt to ch
136f0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
13700 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67  de memory config
13710 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f  uration when loo
13720 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79  kaside.** memory
13730 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65   is in use leave
13740 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  s the configurat
13750 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e  ion unchanged an
13760 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  d returns .** [S
13770 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f  QLITE_BUSY].)^</
13780 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
13790 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
137a0 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a  ABLE_FKEY</dt>.*
137b0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
137c0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
137d0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
137e0 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74   the enforcement
137f0 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   of.** [foreign 
13800 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
13810 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  .  There should 
13820 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
13830 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
13840 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13850 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
13860 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
13870 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  isable FK enforc
13880 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69  ement,.** positi
13890 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20  ve to enable FK 
138a0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e  enforcement or n
138b0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
138c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a   FK enforcement.
138d0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  ** unchanged.  T
138e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
138f0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
13900 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
13910 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
13920 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
13930 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
13940 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  er FK enforcemen
13950 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a  t is off or on.*
13960 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
13970 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
13980 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
13990 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
139a0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
139b0 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f  case the FK enfo
139c0 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20  rcement setting 
139d0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
139e0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
139f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
13a00 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
13a10 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
13a20 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
13a30 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
13a40 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
13a50 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
13a60 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
13a70 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
13a80 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
13a90 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
13aa0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
13ab0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
13ac0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
13ad0 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
13ae0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
13af0 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
13b00 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
13b10 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
13b20 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
13b30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
13b40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13b50 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
13b60 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
13b70 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
13b80 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
13b90 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
13ba0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
13bb0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
13bc0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
13bd0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
13be0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
13bf0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
13c00 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
13c10 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
13c20 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
13c30 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
13c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13c50 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
13c60 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20  IDE       1001  
13c70 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
13c80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13c90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
13ca0 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32  LE_FKEY     1002
13cb0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
13cc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13cd0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
13ce0 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f  TRIGGER  1003  /
13cf0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
13d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13d10 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
13d20 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
13d30 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  t Codes.**.** ^T
13d40 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
13d50 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
13d60 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
13d70 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
13d80 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
13d90 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
13da0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
13db0 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
13dc0 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
13dd0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
13de0 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
13df0 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
13e00 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ity..*/.int sqli
13e10 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
13e20 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
13e30 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
13e40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13e50 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
13e60 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  id.**.** ^Each e
13e70 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74  ntry in an SQLit
13e80 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e  e table has a un
13e90 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
13ea0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
13eb0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
13ec0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
13ed0 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
13ee0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
13ef0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
13f00 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
13f10 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
13f20 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
13f30 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
13f40 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
13f50 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
13f60 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
13f70 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
13f80 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
13f90 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
13fa0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
13fb0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
13fc0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
13fd0 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
13fe0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  d..**.** ^This r
13ff0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
14000 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
14010 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
14020 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
14030 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61  ERT] into the da
14040 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20  tabase from the 
14050 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14060 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
14070 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
14080 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76   ^As of SQLite v
14090 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68  ersion 3.7.7, th
140a0 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72  is routines.** r
140b0 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20  ecords the last 
140c0 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20  insert rowid of 
140d0 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61  both ordinary ta
140e0 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61  bles and [virtua
140f0 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49  l tables]..** ^I
14100 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
14110 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76  [INSERT]s.** hav
14120 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
14130 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65  on that database
14140 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72   connection, zer
14150 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
14160 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
14170 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
14180 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
14190 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
141a0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
141b0 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
141c0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
141d0 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
141e0 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
141f0 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
14200 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
14210 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
14220 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
14230 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
14240 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
14250 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
14260 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
14270 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
14280 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
14290 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
142a0 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
142b0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
142c0 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
142d0 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
142e0 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
142f0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
14300 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
14310 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
14320 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
14330 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
14340 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
14350 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
14360 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
14370 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
14380 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
14390 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
143a0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
143b0 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
143c0 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
143d0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
143e0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
143f0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
14400 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
14410 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
14420 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
14430 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
14440 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
14450 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
14460 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
14470 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
14480 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
14490 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
144a0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
144b0 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
144c0 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
144d0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
144e0 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
144f0 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
14500 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
14510 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
14520 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
14530 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
14540 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
14550 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
14560 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
14570 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
14580 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
14590 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
145a0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
145b0 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
145c0 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
145d0 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
145e0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
145f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
14600 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
14610 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
14620 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
14630 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
14640 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
14650 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
14660 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
14670 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
14680 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
14690 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
146a0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
146b0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
146c0 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
146d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
146e0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
146f0 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
14700 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
14710 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
14720 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
14730 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
14740 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
14750 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
14760 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
14770 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
14780 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
14790 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
147a0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
147b0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
147c0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
147d0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
147e0 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
147f0 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
14800 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
14810 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
14820 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
14830 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
14840 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
14850 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
14860 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
14870 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
14880 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
14890 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
148a0 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
148b0 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
148c0 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
148d0 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
148e0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
148f0 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
14900 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
14910 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
14920 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
14930 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
14940 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
14950 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
14960 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
14970 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
14980 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
14990 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
149a0 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
149b0 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
149c0 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
149d0 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
149e0 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
149f0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
14a00 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
14a10 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
14a20 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
14a30 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
14a40 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
14a50 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
14a60 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
14a70 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
14a80 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
14a90 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
14aa0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
14ab0 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
14ac0 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
14ad0 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
14ae0 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
14af0 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
14b00 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
14b10 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
14b20 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
14b30 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
14b40 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
14b50 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
14b60 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
14b70 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
14b80 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
14b90 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
14ba0 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
14bb0 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
14bc0 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
14bd0 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
14be0 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
14bf0 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
14c00 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
14c10 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
14c20 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
14c30 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
14c40 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
14c50 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
14c60 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
14c70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
14c80 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
14c90 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
14ca0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
14cb0 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
14cc0 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
14cd0 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
14ce0 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
14cf0 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
14d00 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
14d10 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
14d20 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
14d30 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
14d40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
14d50 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
14d60 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
14d70 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
14d80 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
14d90 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
14da0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
14db0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
14dc0 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
14dd0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
14de0 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
14df0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
14e00 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
14e10 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
14e20 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
14e30 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
14e40 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
14e50 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
14e60 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
14e70 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
14e80 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
14e90 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
14ea0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
14eb0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
14ec0 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
14ed0 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
14ee0 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
14ef0 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
14f00 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
14f10 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
14f20 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
14f30 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
14f40 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
14f50 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
14f60 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
14f70 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
14f80 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
14f90 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
14fa0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
14fb0 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
14fc0 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
14fd0 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
14fe0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
14ff0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
15000 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
15010 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
15020 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
15030 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
15040 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
15050 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
15060 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
15070 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
15080 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
15090 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
150a0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
150b0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
150c0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
150d0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
150e0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
150f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15100 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
15110 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
15120 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
15130 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
15140 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
15150 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
15160 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
15170 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
15180 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
15190 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
151a0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
151b0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
151c0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
151d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
151e0 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
151f0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
15200 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
15210 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
15220 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
15230 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
15240 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
15250 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
15260 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
15270 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
15280 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
15290 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
152a0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
152b0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
152c0 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
152d0 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
152e0 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
152f0 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
15300 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
15310 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
15320 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
15330 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
15340 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
15350 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
15360 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
15370 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
15380 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
15390 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
153a0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
153b0 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
153c0 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
153d0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
153e0 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
153f0 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
15400 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
15410 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
15420 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
15430 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
15440 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
15450 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
15460 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
15470 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
15480 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
15490 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
154a0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
154b0 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
154c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
154d0 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
154e0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
154f0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
15500 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
15510 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
15520 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
15530 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
15540 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
15550 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
15560 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
15570 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
15580 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
15590 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
155a0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
155b0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
155c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
155d0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
155e0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
155f0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
15600 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
15610 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
15620 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
15630 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
15640 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
15650 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
15660 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
15670 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
15680 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
15690 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
156a0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
156b0 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
156c0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
156d0 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
156e0 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
156f0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
15700 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
15710 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
15720 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
15730 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
15740 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
15750 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
15760 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
15770 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
15780 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
15790 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
157a0 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
157b0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
157c0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
157d0 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
157e0 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
157f0 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
15800 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
15810 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
15820 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
15830 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
15840 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
15850 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
15860 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
15870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15880 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
15890 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
158a0 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
158b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
158c0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
158d0 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
158e0 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
158f0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
15900 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
15910 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
15920 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
15930 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
15940 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
15950 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
15960 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
15970 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
15980 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
15990 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
159a0 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
159b0 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
159c0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
159d0 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
159e0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
159f0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
15a00 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
15a10 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
15a20 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
15a30 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
15a40 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
15a50 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
15a60 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
15a70 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
15a80 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
15a90 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
15aa0 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
15ab0 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
15ac0 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
15ad0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
15ae0 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
15af0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
15b00 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
15b10 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
15b20 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
15b30 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
15b40 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
15b50 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
15b60 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
15b70 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
15b80 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
15b90 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
15ba0 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
15bb0 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
15bc0 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
15bd0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
15be0 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
15bf0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
15c00 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
15c10 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
15c20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
15c30 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
15c40 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
15c50 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
15c60 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
15c70 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
15c80 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
15c90 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
15ca0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
15cb0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
15cc0 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
15cd0 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
15ce0 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
15cf0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
15d00 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
15d10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
15d20 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
15d30 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
15d40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
15d50 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
15d60 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
15d70 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
15d80 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
15d90 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
15da0 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
15db0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
15dc0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
15dd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15de0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
15df0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
15e00 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
15e10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
15e20 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
15e30 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
15e40 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
15e50 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
15e60 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
15e70 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
15e80 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
15e90 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
15ea0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
15eb0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
15ec0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
15ed0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
15ee0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
15ef0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
15f00 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
15f10 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
15f20 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
15f30 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
15f40 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
15f50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
15f60 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
15f70 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
15f80 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
15f90 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
15fa0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
15fb0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
15fc0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
15fd0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
15fe0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
15ff0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
16000 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
16010 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
16020 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
16030 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
16040 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
16050 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
16060 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
16070 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
16080 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
16090 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
160a0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
160b0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
160c0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
160d0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
160e0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
160f0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
16100 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
16110 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
16120 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
16130 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
16140 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
16150 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
16160 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
16170 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
16180 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
16190 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
161a0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
161b0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
161c0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
161d0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
161e0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
161f0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
16200 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
16210 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
16220 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
16230 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
16240 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
16250 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
16260 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
16270 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
16280 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
16290 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
162a0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
162b0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
162c0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
162d0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
162e0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
162f0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
16300 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
16310 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
16320 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
16330 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
16340 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
16350 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
16360 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
16370 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
16380 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
16390 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
163a0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
163b0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
163c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
163d0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
163e0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
163f0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
16400 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
16410 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
16420 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
16430 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
16440 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
16450 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
16460 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
16470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
16480 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
16490 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
164a0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
164b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
164c0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
164d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
164e0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
164f0 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
16500 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
16510 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
16520 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
16530 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
16540 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
16550 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
16560 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
16570 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
16580 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
16590 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
165a0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
165b0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
165c0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
165d0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
165e0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
165f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
16600 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
16610 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
16620 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
16630 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
16640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
16650 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
16660 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
16670 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
16680 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
16690 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
166a0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
166b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
166c0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
166d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
166e0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
166f0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
16700 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
16710 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
16720 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
16730 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
16740 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
16750 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
16760 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
16770 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
16780 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
16790 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
167a0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
167b0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
167c0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
167d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
167e0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
167f0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
16800 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
16810 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
16820 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
16830 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
16840 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
16850 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
16860 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
16870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
16880 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
16890 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
168a0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
168b0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
168c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
168d0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
168e0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
168f0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
16900 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
16910 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
16920 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
16930 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
16940 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
16950 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
16960 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
16970 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
16980 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
16990 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
169a0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
169b0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
169c0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
169d0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
169e0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
169f0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
16a00 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
16a10 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
16a20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
16a30 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
16a40 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
16a50 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
16a60 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
16a70 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
16a80 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
16a90 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
16aa0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
16ab0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
16ac0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
16ad0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
16ae0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
16af0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
16b00 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
16b10 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
16b20 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
16b30 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
16b40 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
16b50 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
16b60 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
16b70 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
16b80 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
16b90 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
16ba0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
16bb0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
16bc0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
16bd0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
16be0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
16bf0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
16c00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
16c10 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
16c20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
16c30 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
16c40 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
16c50 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
16c60 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
16c70 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
16c80 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
16c90 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
16ca0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
16cb0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
16cc0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
16cd0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
16ce0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
16cf0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
16d00 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
16d10 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
16d20 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
16d30 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
16d40 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
16d50 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
16d60 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
16d70 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
16d80 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
16d90 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
16da0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
16db0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
16dc0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
16dd0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
16de0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
16df0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
16e00 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
16e10 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
16e20 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
16e30 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
16e40 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
16e50 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
16e60 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
16e70 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
16e80 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
16e90 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
16ea0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
16eb0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
16ec0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
16ed0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
16ee0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
16ef0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
16f00 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
16f10 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
16f20 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
16f30 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
16f40 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
16f50 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
16f60 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
16f70 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
16f80 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
16f90 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
16fa0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
16fb0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
16fc0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
16fd0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
16fe0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
16ff0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
17000 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
17010 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
17020 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
17030 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
17040 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
17050 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
17060 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
17070 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
17080 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
17090 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
170a0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
170b0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
170c0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
170d0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
170e0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
170f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17100 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
17110 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
17120 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
17130 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
17140 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
17150 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
17160 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
17170 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
17180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17190 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
171a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
171b0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
171c0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
171d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
171e0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
171f0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
17200 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
17210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
17220 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
17230 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
17240 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
17250 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
17260 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
17270 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
17280 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
17290 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
172a0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
172b0 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
172c0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
172d0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
172e0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
172f0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
17300 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
17310 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
17320 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
17330 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
17340 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
17350 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
17360 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
17370 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
17380 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
17390 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
173a0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
173b0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
173c0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
173d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
173e0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
173f0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
17400 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
17410 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
17420 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
17430 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
17440 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
17450 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
17460 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
17470 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17480 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
17490 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
174a0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
174b0 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
174c0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
174d0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
174e0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
174f0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
17500 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
17510 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
17520 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69   cleared.)^.*/.i
17530 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
17540 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
17550 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
17560 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
17570 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
17580 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
17590 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
175a0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
175b0 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
175c0 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
175d0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
175e0 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
175f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
17600 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
17610 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
17620 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
17630 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
17640 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
17650 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
17660 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
17670 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
17680 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
17690 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
176a0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
176b0 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
176c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
176d0 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
176e0 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
176f0 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
17700 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
17710 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
17720 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
17730 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
17740 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
17750 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
17760 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
17770 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
17780 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
17790 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
177a0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
177b0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
177c0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
177d0 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
177e0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
177f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
17800 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
17810 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
17820 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
17830 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
17840 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
17850 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
17860 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
17870 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
17880 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
17890 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
178a0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
178b0 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
178c0 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
178d0 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
178e0 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
178f0 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
17900 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
17910 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
17920 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
17930 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
17940 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
17950 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
17960 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
17970 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
17980 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
17990 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
179a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
179b0 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
179c0 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
179d0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
179e0 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
179f0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
17a00 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
17a10 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
17a20 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
17a30 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
17a40 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
17a50 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
17a60 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
17a70 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
17a80 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
17a90 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
17aa0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
17ab0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
17ac0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
17ad0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
17ae0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
17af0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
17b00 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
17b10 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
17b20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
17b30 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
17b40 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
17b50 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
17b60 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
17b70 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
17b80 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
17b90 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
17ba0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
17bb0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
17bc0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
17bd0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
17be0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
17bf0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
17c00 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
17c10 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
17c20 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
17c30 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
17c40 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
17c50 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
17c60 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
17c70 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
17c80 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
17c90 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
17ca0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
17cb0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
17cc0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
17cd0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
17ce0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
17cf0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
17d00 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
17d10 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
17d20 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
17d30 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
17d40 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
17d50 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
17d60 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
17d70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
17d80 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
17d90 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
17da0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
17db0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
17dc0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
17dd0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
17de0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
17df0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
17e00 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
17e10 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
17e20 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
17e30 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
17e40 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
17e50 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
17e60 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
17e70 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
17e80 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
17e90 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
17ea0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
17eb0 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
17ec0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
17ed0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
17ee0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
17ef0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
17f00 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
17f10 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
17f20 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
17f30 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
17f40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
17f50 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
17f60 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
17f70 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
17f80 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
17f90 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
17fa0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
17fb0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
17fc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
17fd0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
17fe0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
17ff0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
18000 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
18010 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
18020 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
18030 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
18040 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
18050 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
18060 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
18070 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
18080 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
18090 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
180a0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
180b0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
180c0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
180d0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
180e0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
180f0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
18100 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
18110 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
18120 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
18130 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
18140 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
18150 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
18160 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
18170 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
18180 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
18190 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
181a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
181b0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
181c0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
181d0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
181e0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
181f0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
18200 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
18210 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
18220 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
18230 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
18240 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
18250 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
18260 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
18270 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
18280 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
18290 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
182a0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
182b0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
182c0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
182d0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
182e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
182f0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
18300 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
18310 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
18320 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
18330 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
18340 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
18350 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
18360 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
18370 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
18380 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
18390 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
183a0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
183b0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
183c0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
183d0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
183e0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
183f0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
18400 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18410 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
18420 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
18430 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
18440 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
18450 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
18460 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
18470 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
18480 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
18490 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
184a0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
184b0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
184c0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
184d0 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
184e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
184f0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
18500 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
18510 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
18520 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
18530 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
18540 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
18550 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
18560 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
18570 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
18580 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
18590 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
185a0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
185b0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
185c0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
185d0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
185e0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
185f0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
18600 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
18610 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
18620 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
18630 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
18640 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
18650 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
18660 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
18670 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
18680 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
18690 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
186a0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
186b0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
186c0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
186d0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
186e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
186f0 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
18700 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
18710 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
18720 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
18730 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
18740 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
18750 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
18760 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
18770 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
18780 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
18790 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
187a0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
187b0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
187c0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
187d0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
187e0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
187f0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
18800 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
18810 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
18820 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
18830 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
18840 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
18850 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
18860 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
18870 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
18880 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
18890 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
188a0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
188b0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
188c0 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
188d0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
188e0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
188f0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
18900 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
18910 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
18920 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
18930 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
18940 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
18950 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
18960 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
18970 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
18980 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18990 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
189a0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
189b0 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
189c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
189d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
189e0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
189f0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
18a00 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
18a10 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
18a20 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
18a30 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
18a40 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
18a50 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
18a60 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
18a70 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
18a80 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
18a90 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
18aa0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
18ab0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
18ac0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
18ad0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
18ae0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
18af0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
18b00 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
18b10 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
18b20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
18b30 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
18b40 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
18b50 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
18b60 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
18b70 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
18b80 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
18b90 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
18ba0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
18bb0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
18bc0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
18bd0 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
18be0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
18bf0 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
18c00 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
18c10 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
18c20 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
18c30 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
18c40 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
18c50 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
18c60 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
18c70 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
18c80 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
18c90 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
18ca0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
18cb0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
18cc0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18cd0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
18ce0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
18cf0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
18d00 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
18d10 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
18d20 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
18d30 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
18d40 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
18d50 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
18d60 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
18d70 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
18d80 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
18d90 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
18da0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
18db0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
18dc0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
18dd0 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
18de0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
18df0 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
18e00 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
18e10 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
18e20 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
18e30 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
18e40 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
18e50 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
18e60 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
18e70 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
18e80 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
18e90 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
18ea0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
18eb0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
18ec0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
18ed0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
18ee0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
18ef0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
18f00 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
18f10 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
18f20 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
18f30 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
18f40 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
18f50 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
18f60 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
18f70 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
18f80 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
18f90 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
18fa0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
18fb0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
18fc0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
18fd0 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
18fe0 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
18ff0 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
19000 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
19010 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
19020 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
19030 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
19040 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
19050 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
19060 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
19070 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
19080 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
19090 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
190a0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
190b0 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
190c0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
190d0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
190e0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
190f0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
19100 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
19110 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
19120 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
19130 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
19140 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
19150 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
19160 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
19170 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
19180 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
19190 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
191a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
191b0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
191c0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
191d0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
191e0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
191f0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
19200 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
19210 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
19220 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
19230 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
19240 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
19250 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
19260 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
19270 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
19280 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
19290 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
192a0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
192b0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
192c0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
192d0 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
192e0 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
192f0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
19300 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
19310 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
19320 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
19330 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
19340 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
19350 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
19360 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
19370 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
19380 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
19390 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
193a0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
193b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
193c0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
193d0 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
193e0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
193f0 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
19400 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
19410 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
19420 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
19430 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
19440 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
19450 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
19460 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
19470 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
19480 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
19490 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
194a0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
194b0 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
194c0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
194d0 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
194e0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
194f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19500 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
19510 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
19520 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
19530 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
19540 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
19550 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
19560 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
19570 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
19580 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
19590 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
195a0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
195b0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
195c0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
195d0 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
195e0 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
195f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
19600 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
19610 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
19620 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
19630 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
19640 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
19650 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
19660 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
19670 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
19680 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
19690 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
196a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
196b0 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
196c0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
196d0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
196e0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
196f0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
19700 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
19710 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
19720 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
19730 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
19740 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
19750 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
19760 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
19770 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
19780 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
19790 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
197a0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
197b0 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
197c0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
197d0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
197e0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
197f0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
19800 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
19810 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
19820 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
19830 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
19840 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
19850 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
19860 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
19870 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
19880 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
19890 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
198a0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
198b0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
198c0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
198d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
198e0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
198f0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
19900 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
19910 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
19920 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
19930 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
19940 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
19950 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
19960 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
19970 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
19980 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
19990 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
199a0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
199b0 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
199c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
199d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
199e0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
199f0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
19a00 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
19a10 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
19a20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
19a30 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
19a40 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
19a50 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
19a60 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
19a70 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
19a80 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19a90 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
19aa0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
19ab0 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
19ac0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
19ad0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
19ae0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
19af0 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
19b00 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
19b10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
19b20 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
19b30 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
19b40 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
19b50 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
19b60 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
19b70 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
19b80 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
19b90 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
19ba0 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
19bb0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
19bc0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
19bd0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
19be0 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
19bf0 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
19c00 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
19c10 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
19c20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
19c30 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
19c40 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
19c50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
19c60 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
19c70 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
19c80 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
19c90 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
19ca0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
19cb0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
19cc0 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
19cd0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
19ce0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
19cf0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
19d00 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
19d10 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
19d20 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
19d30 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
19d40 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
19d50 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
19d60 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
19d70 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
19d80 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
19d90 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
19da0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
19db0 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
19dc0 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
19dd0 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
19de0 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
19df0 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
19e00 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
19e10 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
19e20 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
19e30 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
19e40 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
19e50 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
19e60 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
19e70 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
19e80 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
19e90 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
19ea0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
19eb0 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
19ec0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f  .**.** The Windo
19ed0 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
19ee0 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74  layer calls.** t
19ef0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
19f00 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
19f10 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
19f20 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
19f30 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
19f40 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
19f50 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
19f60 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
19f70 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
19f80 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
19f90 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
19fa0 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
19fb0 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
19fc0 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65  ation errors are
19fd0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
19fe0 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72  * they are repor
19ff0 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1a000 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1a010 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1a020 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1a030 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1a040 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1a050 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1a060 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1a070 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1a080 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1a090 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1a0a0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1a0b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1a0c0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1a0d0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1a0e0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1a0f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1a100 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1a110 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1a120 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1a130 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1a140 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1a150 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1a160 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1a170 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1a180 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1a190 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1a1a0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1a1b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1a1c0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1a1d0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
1a1e0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1a1f0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1a200 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1a210 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
1a220 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1a230 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
1a240 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
1a250 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
1a260 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
1a270 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
1a280 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
1a290 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1a2a0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
1a2b0 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
1a2c0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1a2d0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
1a2e0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
1a2f0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
1a300 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
1a310 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
1a320 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1a330 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
1a340 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1a350 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1a360 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
1a370 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
1a380 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
1a390 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
1a3a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1a3b0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1a3c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1a3d0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1a3e0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
1a3f0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1a400 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
1a410 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
1a420 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
1a430 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
1a440 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1a450 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
1a460 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
1a470 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1a480 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
1a490 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
1a4a0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
1a4b0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1a4c0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1a4d0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
1a4e0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
1a4f0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
1a500 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
1a510 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
1a520 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
1a530 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
1a540 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
1a550 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
1a560 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
1a570 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
1a580 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
1a590 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1a5a0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
1a5b0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1a5c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
1a5d0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1a5e0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
1a5f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a600 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1a610 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1a620 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
1a630 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
1a640 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
1a650 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
1a660 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1a670 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
1a680 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1a690 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1a6a0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1a6b0 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1a6c0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1a6d0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1a6e0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1a6f0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1a700 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1a710 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1a720 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1a730 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1a740 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1a750 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1a760 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1a770 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1a780 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1a790 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1a7a0 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1a7b0 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1a7c0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1a7d0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1a7e0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1a7f0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1a800 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1a810 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1a820 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1a830 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1a840 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1a850 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1a860 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1a870 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1a880 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1a890 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1a8a0 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fer P..**.** ^Th
1a8b0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
1a8c0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
1a8d0 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
1a8e0 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
1a8f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1a900 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
1a910 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
1a920 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
1a930 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
1a940 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1a950 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1a960 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1a970 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75  t..** ^On all su
1a980 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
1a990 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
1a9a0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1a9b0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1a9c0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1a9d0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1a9e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1a9f0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1aa00 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1aa10 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1aa20 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1aa30 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1aa40 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1aa50 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1aa60 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1aa70 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1aa80 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1aa90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1aaa0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1aab0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1aac0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1aad0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1aae0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1aaf0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ab00 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1ab10 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1ab20 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1ab30 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1ab40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1ab50 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1ab60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ab70 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1ab80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1ab90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1aba0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1abb0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1abc0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1abd0 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1abe0 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1abf0 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1ac00 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1ac10 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1ac20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1ac30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1ac40 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1ac50 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1ac60 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1ac70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ac80 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1ac90 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1aca0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1acb0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1acc0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1acd0 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1ace0 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1acf0 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1ad00 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1ad10 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1ad20 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1ad30 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1ad40 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1ad50 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1ad60 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1ad70 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1ad80 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ad90 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1ada0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1adb0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1adc0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1add0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1ade0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1adf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ae00 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1ae10 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1ae20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1ae30 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1ae40 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1ae50 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1ae60 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1ae70 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1ae80 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1ae90 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1aea0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1aeb0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1aec0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1aed0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1aee0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1aef0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1af00 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1af10 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1af20 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1af30 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1af40 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1af50 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1af60 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1af70 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1af80 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1af90 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1afa0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1afb0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1afc0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1afd0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1afe0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1aff0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1b000 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1b010 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1b020 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1b030 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1b040 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1b050 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1b060 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1b070 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1b080 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1b090 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1b0a0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1b0b0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1b0c0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1b0d0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1b0e0 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1b0f0 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1b100 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1b110 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1b120 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1b130 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1b140 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1b150 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1b160 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1b170 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1b180 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1b190 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1b1a0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1b1b0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1b1c0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1b1d0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1b1e0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1b1f0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1b200 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1b210 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1b220 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1b230 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1b240 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1b250 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1b260 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1b270 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1b280 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1b290 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1b2a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1b2b0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1b2c0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1b2d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1b2e0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1b2f0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1b300 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1b310 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1b320 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1b330 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1b340 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1b350 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1b360 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1b370 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1b380 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1b390 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1b3a0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1b3b0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1b3c0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1b3d0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1b3e0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1b3f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b400 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1b410 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1b420 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1b430 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1b440 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1b450 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1b460 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1b470 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1b480 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1b490 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1b4a0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1b4b0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1b4c0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1b4d0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1b4e0 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1b4f0 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1b500 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1b510 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1b520 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1b530 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1b540 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1b550 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1b560 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1b570 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1b580 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1b590 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1b5a0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1b5b0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1b5c0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1b5d0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1b5e0 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1b5f0 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1b600 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1b610 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1b620 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1b630 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1b640 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1b650 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1b660 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1b670 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1b680 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b690 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1b6a0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1b6b0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1b6c0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1b6d0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1b6e0 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1b6f0 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1b700 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1b710 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1b720 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1b730 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1b740 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1b750 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1b760 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1b770 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1b780 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1b790 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1b7a0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1b7b0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1b7c0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1b7d0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1b7e0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1b7f0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1b800 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1b810 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1b820 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1b830 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1b840 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1b850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b860 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1b870 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1b880 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1b890 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1b8a0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1b8b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1b8c0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1b8d0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1b8e0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1b8f0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1b900 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1b910 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1b920 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1b930 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1b940 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1b950 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1b960 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1b970 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1b980 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1b990 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1b9a0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1b9b0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1b9c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1b9d0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1b9e0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1b9f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ba00 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1ba10 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1ba20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1ba30 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1ba40 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1ba50 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1ba60 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1ba70 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1ba80 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1ba90 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1baa0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1bab0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1bac0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1bad0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1bae0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1baf0 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1bb00 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1bb10 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1bb20 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1bb30 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1bb40 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1bb50 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1bb60 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1bb70 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1bb80 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
1bb90 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
1bba0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
1bbb0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
1bbc0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1bbd0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1bbe0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1bbf0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
1bc00 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
1bc10 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1bc20 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
1bc30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1bc40 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1bc50 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1bc60 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1bc70 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
1bc80 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
1bc90 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
1bca0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
1bcb0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
1bcc0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
1bcd0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1bce0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
1bcf0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
1bd00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1bd10 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1bd20 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
1bd30 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
1bd40 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1bd50 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
1bd60 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
1bd70 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
1bd80 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52  d as a [SQLITE_R
1bd90 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e  OLLBACK | return
1bda0 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74   code].** from t
1bdb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
1bdc0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
1bdd0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
1bde0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
1bdf0 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
1be00 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1be10 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
1be20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1be30 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
1be40 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
1be50 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
1be60 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
1be70 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1be80 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1be90 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
1bea0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1beb0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1bec0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
1bed0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
1bee0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
1bef0 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
1bf00 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
1bf10 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1bf20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
1bf30 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1bf40 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1bf50 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1bf60 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
1bf70 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
1bf80 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
1bf90 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
1bfa0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
1bfb0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
1bfc0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1bfd0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
1bfe0 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
1bff0 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
1c000 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
1c010 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
1c020 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
1c030 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
1c040 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
1c050 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1c060 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
1c070 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
1c080 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
1c090 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1c0a0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1c0b0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
1c0c0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
1c0d0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1c0e0 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
1c0f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1c100 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1c110 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1c120 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1c130 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
1c140 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
1c150 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
1c160 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
1c170 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1c180 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c190 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
1c1a0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
1c1b0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
1c1c0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
1c1d0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
1c1e0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1c1f0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
1c200 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
1c210 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
1c220 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
1c230 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
1c240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c250 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c260 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
1c270 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
1c280 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
1c290 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
1c2a0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
1c2b0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1c2c0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1c2d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c2e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
1c2f0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
1c300 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1c310 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c320 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c330 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1c340 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
1c350 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1c360 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1c370 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c380 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1c390 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
1c3a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1c3b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c3c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c3d0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1c3e0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
1c3f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1c400 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c410 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c420 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
1c430 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
1c440 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1c450 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c460 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c470 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
1c480 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
1c490 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1c4a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1c4b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c4c0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
1c4d0 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
1c4e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1c4f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1c500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c510 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
1c520 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
1c530 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1c540 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1c550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c560 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
1c570 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
1c580 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1c590 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1c5a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1c5b0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
1c5c0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
1c5d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1c5e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1c5f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1c600 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
1c610 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
1c620 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1c630 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1c640 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1c650 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1c660 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
1c670 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1c680 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1c690 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1c6a0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
1c6b0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
1c6c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1c6d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1c6e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1c6f0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
1c700 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
1c710 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1c720 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1c730 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
1c740 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
1c750 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1c760 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1c770 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c780 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
1c790 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
1c7a0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1c7b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1c7c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c7d0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
1c7e0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
1c7f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1c800 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c810 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c820 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
1c830 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
1c840 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
1c850 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
1c860 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
1c870 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
1c880 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
1c890 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1c8a0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1c8b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c8c0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
1c8d0 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
1c8e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c8f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c900 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c910 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
1c920 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
1c930 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1c940 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c950 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c960 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
1c970 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
1c980 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1c990 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1c9a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c9b0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
1c9c0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
1c9d0 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
1c9e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1c9f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ca00 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
1ca10 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
1ca20 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
1ca30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ca40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1ca50 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
1ca60 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
1ca70 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
1ca80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1ca90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1caa0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1cab0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
1cac0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1cad0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1cae0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
1caf0 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
1cb00 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
1cb10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1cb20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1cb30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1cb40 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
1cb50 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
1cb60 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1cb70 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1cb80 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1cb90 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
1cba0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
1cbb0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1cbc0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1cbd0 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
1cbe0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
1cbf0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1cc00 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
1cc10 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
1cc20 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
1cc30 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
1cc40 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1cc50 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
1cc60 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
1cc70 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
1cc80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
1cc90 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
1cca0 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
1ccb0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
1ccc0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
1ccd0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1cce0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
1ccf0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
1cd00 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
1cd10 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
1cd20 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
1cd30 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
1cd40 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
1cd50 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
1cd60 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1cd70 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1cd80 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
1cd90 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
1cda0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
1cdb0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
1cdc0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
1cdd0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
1cde0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
1cdf0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
1ce00 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
1ce10 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
1ce20 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
1ce30 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
1ce40 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
1ce50 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
1ce60 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
1ce70 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
1ce80 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
1ce90 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
1cea0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
1ceb0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
1cec0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
1ced0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
1cee0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
1cef0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
1cf00 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
1cf10 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
1cf20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
1cf30 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1cf40 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1cf50 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1cf60 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1cf70 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1cf80 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1cf90 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
1cfa0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1cfb0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
1cfc0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1cfd0 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
1cfe0 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
1cff0 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
1d000 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
1d010 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
1d020 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
1d030 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
1d040 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
1d050 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
1d060 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
1d070 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
1d080 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
1d090 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
1d0a0 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
1d0b0 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
1d0c0 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
1d0d0 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
1d0e0 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
1d0f0 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
1d100 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1d110 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
1d120 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
1d130 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
1d140 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
1d150 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
1d160 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
1d170 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
1d180 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1d190 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
1d1a0 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
1d1b0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1d1c0 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  QLite..*/.void *
1d1d0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
1d1e0 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
1d1f0 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
1d200 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
1d210 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
1d220 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
1d230 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
1d240 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
1d250 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
1d260 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
1d270 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
1d280 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1d290 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
1d2a0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
1d2b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1d2c0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1d2d0 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
1d2e0 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
1d2f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1d300 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
1d310 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
1d320 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
1d330 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
1d340 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1d350 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
1d360 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
1d370 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
1d380 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
1d390 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
1d3a0 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
1d3b0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
1d3c0 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
1d3d0 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
1d3e0 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
1d3f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
1d400 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
1d410 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
1d420 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1d430 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
1d440 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
1d450 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
1d460 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72   N is the number
1d470 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
1d480 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
1d490 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
1d4a0 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
1d4b0 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
1d4c0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
1d4d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a  he callback X..*
1d4e0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
1d4f0 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
1d500 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
1d510 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
1d520 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
1d530 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
1d540 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
1d550 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
1d560 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
1d570 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
1d580 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
1d590 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
1d5a0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1d5b0 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
1d5c0 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
1d5d0 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
1d5e0 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
1d5f0 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
1d600 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
1d610 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1d620 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1d630 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
1d640 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
1d650 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
1d660 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
1d670 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
1d680 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
1d690 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
1d6a0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
1d6b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
1d6c0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
1d6d0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
1d6e0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1d6f0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1d700 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d710 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1d720 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
1d730 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
1d740 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1d750 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1d760 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d770 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1d780 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1d790 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1d7a0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1d7b0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1d7c0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
1d7d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
1d7e0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
1d7f0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
1d800 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
1d810 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1d820 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
1d830 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
1d840 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
1d850 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
1d860 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
1d870 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
1d880 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
1d890 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
1d8a0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
1d8b0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
1d8c0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
1d8d0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
1d8e0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1d8f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1d900 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
1d910 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1d920 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
1d930 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1d940 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
1d950 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1d960 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
1d970 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
1d980 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
1d990 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
1d9a0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
1d9b0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
1d9c0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
1d9d0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1d9e0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
1d9f0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
1da00 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
1da10 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
1da20 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
1da30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1da40 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
1da50 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
1da60 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1da70 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
1da80 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
1da90 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
1daa0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1dab0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
1dac0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1dad0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
1dae0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
1daf0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
1db00 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1db10 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
1db20 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
1db30 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
1db40 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
1db50 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
1db60 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
1db70 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
1db80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
1db90 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
1dba0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1dbb0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
1dbc0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1dbd0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
1dbe0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1dbf0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1dc00 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
1dc10 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
1dc20 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1dc30 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
1dc40 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
1dc50 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
1dc60 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
1dc70 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
1dc80 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
1dc90 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
1dca0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1dcb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1dcc0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
1dcd0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
1dce0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
1dcf0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1dd00 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1dd10 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
1dd20 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1dd30 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
1dd40 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
1dd50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
1dd60 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
1dd70 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
1dd80 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
1dd90 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
1dda0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
1ddb0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
1ddc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
1ddd0 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
1dde0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
1ddf0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
1de00 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
1de10 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1de20 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
1de30 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1de40 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
1de50 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1de60 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1de70 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
1de80 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1de90 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
1dea0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1deb0 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
1dec0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
1ded0 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
1dee0 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
1def0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1df00 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1df10 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1df20 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1df30 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1df40 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1df50 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1df60 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1df70 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1df80 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1df90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1dfa0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
1dfb0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1dfc0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1dfd0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1dfe0 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1dff0 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
1e000 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
1e010 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
1e020 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
1e030 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
1e040 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
1e050 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
1e060 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
1e070 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
1e080 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1e090 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1e0a0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1e0b0 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
1e0c0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1e0d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e0e0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1e0f0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1e100 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
1e110 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
1e120 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
1e130 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
1e140 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
1e150 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
1e160 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
1e170 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1e180 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1e190 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1e1a0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
1e1b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
1e1c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e1d0 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
1e1e0 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
1e1f0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1e200 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
1e210 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
1e220 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
1e230 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
1e240 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
1e250 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1e260 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1e270 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
1e280 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1e290 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1e2a0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1e2b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1e2c0 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
1e2d0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
1e2e0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
1e2f0 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
1e300 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
1e310 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
1e320 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1e330 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1e340 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
1e350 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1e360 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1e370 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1e380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1e390 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1e3a0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1e3b0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1e3c0 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1e3d0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1e3e0 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1e3f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1e400 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
1e410 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
1e420 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
1e430 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1e440 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1e450 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
1e460 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
1e470 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
1e480 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1e490 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1e4a0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
1e4b0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
1e4c0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1e4d0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
1e4e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1e4f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1e500 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1e510 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e520 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
1e530 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
1e540 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1e550 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
1e560 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
1e570 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
1e580 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1e590 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
1e5a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
1e5b0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1e5c0 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
1e5d0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1e5e0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1e5f0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
1e600 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e610 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
1e620 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
1e630 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1e640 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1e650 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
1e660 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1e670 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
1e680 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1e690 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1e6a0 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1e6b0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1e6c0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1e6d0 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1e6e0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1e6f0 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
1e700 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
1e710 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
1e720 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1e730 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1e740 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
1e750 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1e760 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
1e770 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
1e780 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
1e790 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
1e7a0 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
1e7b0 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
1e7c0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
1e7d0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
1e7e0 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
1e7f0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
1e800 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
1e810 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
1e820 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
1e830 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
1e840 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
1e850 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
1e860 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
1e870 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1e880 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1e890 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1e8a0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
1e8b0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1e8c0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1e8d0 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
1e8e0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1e8f0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1e900 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
1e910 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
1e920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1e930 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
1e940 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
1e950 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
1e960 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
1e970 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
1e980 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
1e990 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
1e9a0 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
1e9b0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
1e9c0 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
1e9d0 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
1e9e0 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
1e9f0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1ea00 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
1ea10 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
1ea20 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
1ea30 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
1ea40 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
1ea50 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
1ea60 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
1ea70 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
1ea80 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
1ea90 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
1eaa0 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
1eab0 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
1eac0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
1ead0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
1eae0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1eaf0 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
1eb00 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
1eb10 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
1eb20 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
1eb30 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
1eb40 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
1eb50 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
1eb60 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
1eb70 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
1eb80 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
1eb90 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
1eba0 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
1ebb0 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
1ebc0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
1ebd0 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
1ebe0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
1ebf0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1ec00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1ec10 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
1ec20 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
1ec30 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
1ec40 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
1ec50 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
1ec60 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
1ec70 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
1ec80 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
1ec90 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
1eca0 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
1ecb0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1ecc0 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
1ecd0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
1ece0 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
1ecf0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1ed00 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
1ed10 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
1ed20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
1ed30 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
1ed40 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
1ed50 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
1ed60 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
1ed70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
1ed80 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
1ed90 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
1eda0 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
1edb0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
1edc0 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
1edd0 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
1ede0 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
1edf0 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
1ee00 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
1ee10 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
1ee20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
1ee30 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
1ee40 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
1ee50 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
1ee60 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
1ee70 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
1ee80 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
1ee90 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1eea0 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
1eeb0 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64  th. .** ^On wind
1eec0 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
1eed0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
1eee0 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
1eef0 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
1ef00 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
1ef10 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  "C:")..**.** [[c
1ef20 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
1ef30 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
1ef40 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
1ef50 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
1ef60 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
1ef70 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
1ef80 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
1ef90 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
1efa0 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
1efb0 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
1efc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
1efd0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
1efe0 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ts the following
1eff0 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72   three query par
1f000 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
1f010 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
1f020 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
1f030 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
1f040 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
1f050 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
1f060 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
1f070 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
1f080 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
1f090 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1f0a0 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
1f0b0 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
1f0c0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1f0d0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
1f0e0 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
1f0f0 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
1f100 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
1f110 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
1f120 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
1f130 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
1f140 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
1f150 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
1f160 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
1f170 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
1f180 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
1f190 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
1f1a0 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
1f1b0 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
1f1c0 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
1f1d0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
1f1e0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
1f1f0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
1f200 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1f210 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1f220 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
1f230 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
1f240 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
1f250 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
1f260 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
1f270 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20 20  , "rw" or.**    
1f280 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70 74 69   "rwc". Attempti
1f290 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
1f2a0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
1f2b0 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a  is an error)^. .
1f2c0 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
1f2d0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
1f2e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1f2f0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1f300 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
1f310 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
1f320 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
1f330 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
1f340 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
1f350 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
1f360 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
1f370 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1f380 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
1f390 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
1f3a0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
1f3b0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
1f3c0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1f3d0 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
1f3e0 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
1f3f0 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
1f400 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
1f410 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
1f420 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
1f430 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
1f440 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
1f450 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
1f460 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
1f470 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
1f480 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
1f490 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
1f4a0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 5e  E_OPEN_CREATE. ^
1f4b0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
1f4c0 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20 20 20  v2() is .**     
1f4d0 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e 20 65  used, it is an e
1f4e0 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
1f4f0 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  a value for the 
1f500 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
1f510 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20 20 6c  hat is .**     l
1f520 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
1f530 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
1f540 69 65 64 20 62 79 20 74 68 65 20 66 6c 61 67 73  ied by the flags
1f550 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
1f560 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70 61 72  hird .**     par
1f570 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 20  ameter..**.**   
1f580 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
1f590 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
1f5a0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
1f5b0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
1f5c0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
1f5d0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
1f5e0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
1f5f0 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
1f600 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
1f610 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
1f620 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
1f630 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
1f640 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
1f650 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
1f660 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
1f670 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
1f680 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
1f690 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
1f6a0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
1f6b0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
1f6c0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1f6d0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
1f6e0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
1f6f0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
1f700 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
1f710 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
1f720 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
1f730 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
1f740 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
1f750 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20  s any behaviour 
1f760 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
1f770 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
1f780 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1f790 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
1f7a0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
1f7b0 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  flag..** </ul>.*
1f7c0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
1f7d0 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
1f7e0 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
1f7f0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
1f800 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
1f810 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
1f820 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1f830 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
1f840 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
1f850 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
1f860 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
1f870 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
1f880 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
1f890 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
1f8a0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
1f8b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1f8c0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
1f8d0 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
1f8e0 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
1f8f0 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
1f900 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
1f910 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
1f920 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
1f930 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
1f940 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
1f950 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
1f960 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
1f970 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
1f980 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
1f990 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
1f9a0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
1f9b0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
1f9c0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
1f9d0 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
1f9e0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
1f9f0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
1fa00 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
1fa10 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
1fa20 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
1fa30 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
1fa40 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
1fa50 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
1fa60 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
1fa70 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
1fa80 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
1fa90 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
1faa0 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
1fab0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
1fac0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
1fad0 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
1fae0 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
1faf0 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
1fb00 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
1fb10 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
1fb20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
1fb30 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
1fb40 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
1fb50 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
1fb60 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
1fb70 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
1fb80 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
1fb90 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
1fba0 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
1fbb0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
1fbc0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
1fbd0 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
1fbe0 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
1fbf0 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
1fc00 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
1fc10 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
1fc20 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
1fc30 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
1fc40 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
1fc50 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
1fc60 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
1fc70 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
1fc80 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
1fc90 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
1fca0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
1fcb0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
1fcc0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
1fcd0 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
1fce0 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
1fcf0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1fd00 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
1fd10 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
1fd20 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
1fd30 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
1fd40 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
1fd50 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
1fd60 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
1fd70 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20  vfs=unix-nolock 
1fd80 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
1fd90 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
1fda0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
1fdb0 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
1fdc0 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63   VFS "unix-noloc
1fdd0 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  k"..** <tr><td> 
1fde0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
1fdf0 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
1fe00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
1fe10 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
1fe20 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
1fe30 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
1fe40 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
1fe50 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
1fe60 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
1fe70 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
1fe80 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
1fe90 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
1fea0 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
1feb0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
1fec0 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
1fed0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
1fee0 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
1fef0 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
1ff00 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
1ff10 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
1ff20 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
1ff30 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
1ff40 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
1ff50 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
1ff60 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
1ff70 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
1ff80 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
1ff90 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
1ffa0 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
1ffb0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
1ffc0 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
1ffd0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
1ffe0 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
1fff0 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
20000 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
20010 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
20020 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
20030 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
20040 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
20050 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
20060 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
20070 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
20080 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
20090 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
200a0 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
200b0 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
200c0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
200d0 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
200e0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
200f0 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
20100 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
20110 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
20120 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
20130 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
20140 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
20150 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
20160 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
20170 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
20180 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
20190 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
201a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
201b0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
201c0 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20  en_v2()..*/.int 
201d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
201e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
201f0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
20200 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
20210 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
20220 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
20230 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
20240 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
20250 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
20260 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
20270 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
20280 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
20290 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
202a0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
202b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
202c0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
202d0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
202e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
202f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
20300 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
20310 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
20320 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
20330 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
20340 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
20350 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
20360 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
20370 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
20380 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
20390 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
203a0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
203b0 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
203c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
203d0 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
203e0 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
203f0 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
20400 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
20410 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
20420 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
20430 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
20440 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
20450 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
20460 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
20470 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
20480 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
20490 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
204a0 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
204b0 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
204c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
204d0 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
204e0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
204f0 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
20500 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
20510 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
20520 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
20530 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
20540 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
20550 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
20560 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
20570 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
20580 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
20590 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
205a0 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
205b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
205c0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
205d0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
205e0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
205f0 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
20600 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
20610 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
20620 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
20630 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
20640 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
20650 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
20660 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
20670 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
20680 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
20690 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
206a0 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
206b0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
206c0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
206d0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
206e0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
206f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
20700 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
20710 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
20720 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
20730 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
20740 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
20750 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
20760 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
20770 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
20780 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
20790 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
207a0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
207b0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
207c0 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
207d0 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
207e0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
207f0 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
20800 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
20810 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
20820 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
20830 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
20840 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
20850 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
20860 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
20870 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
20880 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
20890 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
208a0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
208b0 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
208c0 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
208d0 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
208e0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
208f0 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
20900 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
20910 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
20920 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
20930 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
20940 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
20950 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
20960 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
20970 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
20980 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
20990 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
209a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
209b0 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
209c0 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
209d0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
209e0 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
209f0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
20a00 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
20a10 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
20a20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
20a30 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
20a40 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
20a50 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
20a60 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
20a70 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
20a80 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
20a90 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
20aa0 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
20ab0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
20ac0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
20ad0 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
20ae0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
20af0 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
20b00 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
20b10 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
20b20 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
20b30 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
20b40 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
20b50 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
20b60 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
20b70 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
20b80 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
20b90 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
20ba0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
20bb0 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
20bc0 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  rable..*/.const 
20bd0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
20be0 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
20bf0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
20c00 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
20c10 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
20c20 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
20c30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
20c40 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
20c50 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
20c60 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
20c70 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
20c80 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
20c90 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
20ca0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
20cb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20cc0 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
20cd0 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
20ce0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
20cf0 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
20d00 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
20d10 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
20d20 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
20d30 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
20d40 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
20d50 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
20d60 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
20d70 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
20d80 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
20d90 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
20da0 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
20db0 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
20dc0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
20dd0 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
20de0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
20df0 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
20e00 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
20e10 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
20e20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
20e30 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
20e40 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
20e50 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
20e60 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
20e70 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
20e80 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
20e90 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
20ea0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
20eb0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
20ec0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
20ed0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
20ee0 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
20ef0 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
20f00 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
20f10 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
20f20 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
20f30 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
20f40 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
20f50 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
20f60 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
20f70 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
20f80 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
20f90 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
20fa0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
20fb0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
20fc0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
20fd0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
20fe0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
20ff0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
21000 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
21010 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
21020 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
21030 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
21040 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
21050 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
21060 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
21070 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
21080 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
21090 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
210a0 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
210b0 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
210c0 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
210d0 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
210e0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
210f0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
21100 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
21110 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
21120 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
21130 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
21140 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
21150 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
21160 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
21170 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
21180 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
21190 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
211a0 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
211b0 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
211c0 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
211d0 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
211e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
211f0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
21200 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
21210 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
21220 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
21230 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
21240 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
21250 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
21260 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
21270 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
21280 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
21290 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
212a0 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
212b0 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
212c0 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
212d0 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
212e0 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
212f0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
21300 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
21310 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
21320 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
21330 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
21340 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
21350 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
21360 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
21370 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
21380 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
21390 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
213a0 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
213b0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
213c0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
213d0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
213e0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
213f0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
21400 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
21410 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
21420 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
21430 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
21440 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
21450 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
21460 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
21470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
21480 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
21490 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
214a0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
214b0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
214c0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
214d0 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
214e0 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
214f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21500 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
21510 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
21520 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
21530 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
21540 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
21550 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
21560 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
21570 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
21580 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
21590 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
215a0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
215b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
215c0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
215d0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
215e0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
215f0 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
21600 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
21610 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
21620 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
21630 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
21640 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
21650 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
21660 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
21670 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
21680 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
21690 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
216a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
216b0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
216c0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
216d0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
216e0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
216f0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
21700 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
21710 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
21720 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
21730 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
21740 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
21750 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
21760 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
21770 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
21780 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
21790 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
217a0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
217b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
217c0 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
217d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
217e0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
217f0 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
21800 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
21810 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
21820 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
21830 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
21840 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
21850 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
21860 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
21870 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
21880 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
21890 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
218a0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
218b0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
218c0 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
218d0 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
218e0 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
218f0 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
21900 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
21910 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
21920 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
21930 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
21940 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
21950 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
21960 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
21970 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
21980 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
21990 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
219a0 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
219b0 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
219c0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
219d0 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
219e0 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
219f0 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
21a00 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
21a10 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
21a20 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
21a30 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
21a40 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
21a50 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
21a60 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
21a70 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
21a80 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
21a90 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
21aa0 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
21ab0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
21ac0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
21ad0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
21ae0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
21af0 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
21b00 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
21b10 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
21b20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
21b30 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
21b40 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
21b50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
21b60 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
21b70 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
21b80 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
21b90 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
21ba0 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
21bb0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
21bc0 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
21bd0 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
21be0 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
21bf0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
21c00 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
21c10 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
21c20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
21c30 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
21c40 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
21c50 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
21c60 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
21c70 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
21c80 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
21c90 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
21ca0 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
21cb0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
21cc0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
21cd0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
21ce0 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
21cf0 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
21d00 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
21d10 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
21d20 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
21d30 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
21d40 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
21d50 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
21d60 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
21d70 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
21d80 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
21d90 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
21da0 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
21db0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
21dc0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
21dd0 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
21de0 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
21df0 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
21e00 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
21e10 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
21e20 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
21e30 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
21e40 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
21e50 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
21e60 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
21e70 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
21e80 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
21e90 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
21ea0 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
21eb0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
21ec0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
21ed0 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
21ee0 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
21ef0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
21f00 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
21f10 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
21f20 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
21f30 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
21f40 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
21f50 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
21f60 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
21f70 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
21f80 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
21f90 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
21fa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21fb0 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
21fc0 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
21fd0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
21fe0 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
21ff0 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
22000 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
22010 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
22020 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
22030 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
22040 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
22050 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
22060 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
22070 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
22080 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
22090 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
220a0 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
220b0 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
220c0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
220d0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
220e0 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
220f0 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
22100 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
22110 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
22120 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
22130 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
22140 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
22150 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
22160 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
22170 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e  or table row, in
22180 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a   bytes.<dd>)^.**
22190 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
221a0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20  IT_SQL_LENGTH]] 
221b0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
221c0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
221d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
221e0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
221f0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
22200 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
22210 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
22220 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d  E_LIMIT_COLUMN]]
22230 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
22240 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
22250 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
22260 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
22270 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
22280 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
22290 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
222a0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
222b0 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
222c0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
222d0 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
222e0 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
222f0 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
22300 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
22310 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
22320 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20  IT_EXPR_DEPTH]] 
22330 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
22340 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
22350 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
22360 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
22370 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
22380 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
22390 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
223a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
223b0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e  POUND_SELECT]] ^
223c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
223d0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
223e0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
223f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
22400 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
22410 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
22420 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
22430 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
22440 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20  LIMIT_VDBE_OP]] 
22450 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
22460 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
22470 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
22480 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
22490 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
224a0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
224b0 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
224c0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
224d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  QL statement.  T
224e0 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  his limit is not
224f0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e   currently.** en
22500 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74  forced, though t
22510 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64  hat might be add
22520 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  ed in some futur
22530 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
22540 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  SQLite.</dd>)^.*
22550 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
22560 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
22570 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
22580 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
22590 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
225a0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
225b0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
225c0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
225d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
225e0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
225f0 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
22600 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
22610 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22620 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
22630 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
22640 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
22650 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
22660 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
22670 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
22680 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
22690 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
226a0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
226b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
226c0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
226d0 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
226e0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
226f0 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
22700 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
22710 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
22720 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
22730 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
22740 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
22750 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
22760 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
22770 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
22780 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
22790 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
227a0 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
227b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
227c0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
227d0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
227e0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
227f0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
22800 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
22810 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
22820 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
22830 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
22840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
22850 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
22860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
22870 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22880 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
22890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
228a0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
228b0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
228c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
228d0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
228e0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
228f0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
22900 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
22910 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
22920 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
22930 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
22940 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
22950 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
22960 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
22970 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
22980 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
22990 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
229a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
229b0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
229c0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
229d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
229e0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
229f0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
22a00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
22a10 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
22a20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
22a30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
22a40 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
22a50 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a          10../*.*
22a60 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
22a70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
22a80 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
22a90 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
22aa0 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
22ab0 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
22ac0 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
22ad0 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
22ae0 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
22af0 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
22b00 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
22b10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
22b20 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
22b30 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
22b40 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
22b50 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
22b60 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
22b70 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
22b80 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
22b90 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
22ba0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
22bb0 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
22bc0 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
22bd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
22be0 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
22bf0 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
22c00 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
22c10 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
22c20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
22c30 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
22c40 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
22c50 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
22c60 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
22c70 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
22c80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22c90 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
22ca0 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
22cb0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
22cc0 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
22cd0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
22ce0 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
22cf0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
22d00 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
22d10 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
22d20 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
22d30 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
22d40 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
22d50 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
22d60 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
22d70 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
22d80 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
22d90 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
22da0 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65  from zSql.  ^Whe
22db0 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
22dc0 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
22dd0 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
22de0 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
22df0 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
22e00 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
22e10 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
22e20 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
22e30 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
22e40 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
22e50 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
22e60 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
22e70 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
22e80 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
22e90 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
22ea0 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
22eb0 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
22ec0 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
22ed0 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
22ee0 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
22ef0 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
22f00 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
22f10 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
22f20 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
22f30 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
22f40 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73 20  r bytes as this 
22f50 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f  saves SQLite fro
22f60 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d  m having to.** m
22f70 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
22f80 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a  e input string..
22f90 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
22fa0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
22fb0 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
22fc0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
22fd0 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
22fe0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
22ff0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
23000 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
23010 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
23020 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
23030 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
23040 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
23050 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
23060 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
23070 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
23080 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
23090 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
230a0 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
230b0 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
230c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
230d0 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
230e0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
230f0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
23100 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
23110 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
23120 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
23130 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
23140 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
23150 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
23160 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
23170 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
23180 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
23190 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
231a0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
231b0 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
231c0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
231d0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
231e0 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
231f0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
23200 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
23210 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
23220 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
23230 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
23240 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
23250 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
23260 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
23270 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
23280 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
23290 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
232a0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
232b0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
232c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
232d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
232e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
232f0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
23300 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
23310 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
23320 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
23330 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
23340 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
23350 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
23360 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
23370 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
23380 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
23390 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
233a0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
233b0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
233c0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
233d0 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
233e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
233f0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
23400 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
23410 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
23420 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
23430 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
23440 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
23450 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
23460 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
23470 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
23480 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
23490 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
234a0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
234b0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
234c0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
234d0 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
234e0 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
234f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23500 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
23510 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
23520 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
23530 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
23540 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20  un it again..** 
23550 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
23560 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
23570 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
23580 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
23590 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
235a0 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
235b0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
235c0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
235d0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
235e0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
235f0 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
23600 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
23610 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
23620 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
23630 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
23640 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
23650 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
23660 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
23670 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
23680 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
23690 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
236a0 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
236b0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
236c0 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
236d0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
236e0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
236f0 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
23700 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
23710 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
23720 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
23730 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
23740 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
23750 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
23760 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
23770 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
23780 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
23790 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
237a0 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
237b0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
237c0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
237d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
237e0 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
237f0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
23800 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
23810 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
23820 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
23830 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
23840 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23850 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
23860 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
23870 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
23880 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
23890 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
238a0 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
238b0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
238c0 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
238d0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
238e0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
238f0 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
23900 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
23910 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
23920 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
23930 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
23940 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
23950 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
23960 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
23970 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
23980 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
23990 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
239a0 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
239b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
239c0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20  enabled..** the 
239d0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
239e0 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
239f0 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
23a00 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
23a10 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
23a20 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
23a30 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
23a40 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
23a50 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
23a60 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
23a70 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
23a80 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
23a90 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
23aa0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
23ab0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
23ac0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
23ad0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
23ae0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
23af0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
23b00 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
23b10 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
23b20 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
23b30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
23b40 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
23b50 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
23b60 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
23b70 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
23b80 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
23b90 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
23ba0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
23bb0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
23bc0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
23bd0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
23be0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
23bf0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
23c00 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
23c10 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
23c20 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
23c30 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
23c40 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
23c50 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
23c60 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
23c70 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
23c80 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
23c90 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
23ca0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
23cb0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
23cc0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
23cd0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
23ce0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
23cf0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
23d00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
23d10 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
23d20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
23d30 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
23d40 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
23d50 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
23d60 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
23d70 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
23d80 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
23d90 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
23da0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
23db0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
23dc0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
23dd0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
23de0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
23df0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
23e00 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
23e10 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
23e20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
23e30 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
23e40 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
23e50 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
23e60 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
23e70 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
23e80 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
23e90 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
23ea0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
23eb0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
23ec0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
23ed0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
23ee0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
23ef0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
23f00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
23f10 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
23f20 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54  ent SQL.**.** ^T
23f30 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
23f40 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
23f50 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
23f60 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
23f70 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
23f80 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
23f90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23fa0 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
23fb0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
23fc0 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
23fd0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
23fe0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
23ff0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
24000 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  _v2()]..*/.const
24010 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
24020 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
24030 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
24040 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
24050 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
24060 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
24070 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a  he Database.**.*
24080 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
24090 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
240a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
240b0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
240c0 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
240d0 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
240e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
240f0 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
24100 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
24110 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
24120 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
24130 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
24140 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
24150 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
24160 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
24170 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
24180 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
24190 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
241a0 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
241b0 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
241c0 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
241d0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
241e0 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
241f0 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
24200 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
24210 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
24220 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
24230 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
24240 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
24250 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
24260 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
24270 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
24280 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
24290 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
242a0 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
242b0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
242c0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
242d0 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
242e0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
242f0 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
24300 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
24310 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
24320 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
24330 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
24340 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
24350 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
24360 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
24370 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
24380 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
24390 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
243a0 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
243b0 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
243c0 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
243d0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
243e0 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
243f0 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
24400 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
24410 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
24420 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
24430 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
24440 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
24450 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
24460 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
24470 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
24480 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
24490 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
244a0 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
244b0 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
244c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
244d0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
244e0 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
244f0 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
24500 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
24510 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
24520 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
24530 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
24540 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
24550 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
24560 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
24570 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
24580 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71   disk..*/.int sq
24590 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
245a0 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
245b0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
245c0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
245d0 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
245e0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
245f0 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a   Been Reset.**.*
24600 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
24610 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
24620 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
24630 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
24640 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
24650 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
24660 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
24670 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
24680 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
24690 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
246a0 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d  s not run to com
246b0 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68  pletion and/or h
246c0 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20  as not .** been 
246d0 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
246e0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
246f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
24700 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
24710 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24720 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
24730 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
24740 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
24750 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
24760 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
24770 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
24780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24790 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
247a0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
247b0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
247c0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
247d0 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
247e0 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
247f0 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
24800 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
24810 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
24820 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
24830 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24840 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
24850 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
24860 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
24870 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
24880 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
24890 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
248a0 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
248b0 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
248c0 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
248d0 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
248e0 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
248f0 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
24900 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
24910 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24920 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
24930 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
24940 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
24950 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
24960 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
24970 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
24980 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
24990 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
249a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
249b0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
249c0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
249d0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
249e0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
249f0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
24a00 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
24a10 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
24a20 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
24a30 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
24a40 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
24a50 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
24a60 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
24a70 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
24a80 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
24a90 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
24aa0 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
24ab0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
24ac0 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
24ad0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
24ae0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
24af0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
24b00 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
24b10 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
24b20 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
24b30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
24b40 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
24b50 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
24b60 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
24b70 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
24b80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24b90 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
24ba0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
24bb0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
24bc0 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
24bd0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
24be0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
24bf0 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
24c00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
24c10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
24c20 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
24c30 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
24c40 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
24c50 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
24c60 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
24c70 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
24c80 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
24c90 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
24ca0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
24cb0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
24cc0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
24cd0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
24ce0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
24cf0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
24d00 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
24d10 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
24d20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
24d30 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
24d40 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
24d50 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
24d60 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
24d70 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
24d80 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
24d90 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
24da0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
24db0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
24dc0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
24dd0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
24de0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
24df0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
24e00 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
24e10 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
24e20 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
24e30 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
24e40 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
24e50 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
24e60 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
24e70 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
24e80 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
24e90 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
24ea0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
24eb0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
24ec0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
24ed0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
24ee0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
24ef0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24f00 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
24f10 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
24f20 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
24f30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
24f40 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
24f50 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
24f60 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
24f70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
24f80 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
24f90 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
24fa0 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
24fb0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
24fc0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
24fd0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
24fe0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
24ff0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
25000 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
25010 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
25020 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
25030 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
25040 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
25050 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
25060 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
25070 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
25080 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
25090 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
250a0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
250b0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
250c0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
250d0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
250e0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
250f0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
25100 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
25110 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
25120 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
25130 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
25140 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
25150 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
25160 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
25170 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
25180 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
25190 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
251a0 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
251b0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
251c0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
251d0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
251e0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
251f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25200 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
25210 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
25220 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
25230 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
25240 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
25250 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
25260 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
25270 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
25280 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
25290 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
252a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
252b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
252c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
252d0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
252e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
252f0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
25300 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
25310 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
25320 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
25330 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
25340 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
25350 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
25360 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
25370 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
25380 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
25390 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
253a0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
253b0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
253c0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
253d0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
253e0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
253f0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
25400 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
25410 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
25420 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
25430 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
25440 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
25450 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
25460 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
25470 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
25480 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
25490 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
254a0 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
254b0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
254c0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
254d0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
254e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
254f0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
25500 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
25510 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
25520 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
25530 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
25540 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
25550 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
25560 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
25570 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
25580 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
25590 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
255a0 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
255b0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
255c0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
255d0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
255e0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
255f0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
25600 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
25610 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
25620 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
25630 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
25640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
25650 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
25660 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
25670 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
25680 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
25690 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
256a0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
256b0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
256c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
256d0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
256e0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
256f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
25700 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
25710 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
25720 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
25730 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
25740 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
25750 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
25760 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
25770 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
25780 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
25790 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
257a0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
257b0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
257c0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
257d0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
257e0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
257f0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
25800 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
25810 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
25820 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
25830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25840 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25850 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
25860 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
25870 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
25880 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
25890 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
258a0 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
258b0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
258c0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
258d0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
258e0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
258f0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
25900 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
25910 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
25920 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
25930 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
25940 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
25950 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
25960 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
25970 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
25980 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
25990 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
259a0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
259b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
259c0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
259d0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
259e0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
259f0 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
25a00 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
25a10 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
25a20 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
25a30 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
25a40 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
25a50 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
25a60 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
25a70 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
25a80 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
25a90 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
25aa0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
25ab0 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
25ac0 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
25ad0 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
25ae0 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
25af0 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
25b00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
25b10 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20  t16() then that 
25b20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
25b30 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
25b40 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
25b50 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
25b60 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
25b70 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
25b80 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
25b90 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
25ba0 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
25bb0 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
25bc0 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
25bd0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
25be0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
25bf0 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
25c00 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
25c10 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
25c20 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
25c30 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
25c40 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
25c50 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
25c60 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
25c70 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
25c80 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
25c90 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
25ca0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25cb0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
25cc0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
25cd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
25ce0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
25cf0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
25d00 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
25d10 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
25d20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
25d30 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
25d40 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
25d50 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
25d60 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
25d70 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
25d80 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
25d90 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
25da0 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
25db0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
25dc0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
25dd0 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
25de0 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
25df0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
25e00 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
25e10 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
25e20 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
25e30 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
25e40 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
25e50 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
25e60 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
25e70 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
25e80 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
25e90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
25ea0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
25eb0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
25ec0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
25ed0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
25ee0 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
25ef0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
25f00 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
25f10 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
25f20 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
25f30 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
25f40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
25f50 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
25f60 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
25f70 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
25f80 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
25f90 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
25fa0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
25fb0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
25fc0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
25fd0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
25fe0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
25ff0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
26000 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
26010 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
26020 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
26030 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
26040 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
26050 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
26060 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
26070 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
26080 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
26090 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
260a0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
260b0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
260c0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
260d0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
260e0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
260f0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
26100 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
26110 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
26120 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
26130 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
26140 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
26150 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26160 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
26170 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
26180 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
26190 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
261a0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
261b0 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
261c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
261d0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
261e0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
261f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
26200 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
26210 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
26220 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
26230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26240 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
26250 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
26260 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
26270 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
26280 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
26290 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
262a0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
262b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
262c0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
262d0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
262e0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
262f0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
26300 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
26310 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
26320 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
26330 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
26340 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
26350 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
26360 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
26370 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
26380 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
26390 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
263a0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
263b0 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
263c0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
263d0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
263e0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
263f0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
26400 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26410 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
26420 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26430 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
26440 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
26450 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
26460 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
26470 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
26480 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26490 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
264a0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
264b0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
264c0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
264d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
264e0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
264f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
26500 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26510 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
26520 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
26530 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
26540 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
26550 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
26560 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
26570 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
26580 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
26590 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
265a0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
265b0 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
265c0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
265d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
265e0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
265f0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
26600 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
26610 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
26620 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
26630 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
26640 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
26650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
26660 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
26670 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
26680 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
26690 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
266a0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
266b0 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
266c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
266d0 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
266e0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
266f0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
26700 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
26710 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26720 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
26730 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
26740 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
26750 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
26760 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
26770 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
26780 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
26790 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
267a0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
267b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
267c0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
267d0 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
267e0 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
267f0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
26800 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
26810 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
26820 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
26830 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
26840 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
26850 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
26860 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
26870 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
26880 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
26890 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
268a0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
268b0 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
268c0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
268d0 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
268e0 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
268f0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
26900 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
26910 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
26920 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
26930 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
26940 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
26950 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
26960 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
26970 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
26980 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
26990 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
269a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
269b0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
269c0 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
269d0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
269e0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
269f0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
26a00 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
26a10 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
26a20 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
26a30 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26a40 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
26a50 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
26a60 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
26a70 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
26a80 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
26a90 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
26aa0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
26ab0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
26ac0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
26ad0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
26ae0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
26af0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
26b00 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
26b10 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
26b20 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
26b30 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
26b40 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
26b50 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
26b60 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
26b70 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
26b80 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
26b90 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
26ba0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
26bb0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
26bc0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
26bd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
26be0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
26bf0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
26c00 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
26c10 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
26c20 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
26c30 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
26c40 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
26c50 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
26c60 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
26c70 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
26c80 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
26c90 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
26ca0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
26cb0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
26cc0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
26cd0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
26ce0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
26cf0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
26d00 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
26d10 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
26d20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
26d30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
26d40 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
26d50 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
26d60 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
26d70 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
26d80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26d90 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
26da0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
26db0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
26dc0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
26dd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26de0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26df0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
26e00 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
26e10 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
26e20 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
26e30 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
26e40 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
26e50 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
26e60 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
26e70 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
26e80 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
26e90 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
26ea0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
26eb0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
26ec0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
26ed0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
26ee0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
26ef0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
26f00 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
26f10 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
26f20 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
26f30 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
26f40 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
26f50 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
26f60 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
26f70 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
26f80 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
26f90 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
26fa0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
26fb0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
26fc0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
26fd0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26fe0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
26ff0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
27000 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
27010 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
27020 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
27030 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
27040 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
27050 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
27060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
27070 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
27080 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
27090 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
270a0 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
270b0 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
270c0 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
270d0 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
270e0 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
270f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
27100 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
27110 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27120 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
27130 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
27140 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
27150 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
27160 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27170 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
27180 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
27190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
271a0 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
271b0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
271c0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
271d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
271e0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
271f0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
27200 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
27210 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
27220 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
27230 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
27240 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
27250 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
27260 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
27270 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
27280 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
27290 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
272a0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
272b0 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
272c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
272d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
272e0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
272f0 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
27300 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
27310 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73   Set.**.** ^Thes
27320 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
27330 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
27340 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
27350 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
27360 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
27370 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
27380 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
27390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
273a0 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
273b0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
273c0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
273d0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
273e0 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
273f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
27400 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
27410 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
27420 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
27430 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
27440 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
27450 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
27460 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
27470 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
27480 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
27490 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
274a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
274b0 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
274c0 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
274d0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
274e0 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
274f0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
27500 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
27510 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
27520 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
27530 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
27540 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
27550 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
27560 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
27570 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
27580 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
27590 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
275a0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
275b0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
275c0 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
275d0 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
275e0 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
275f0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
27600 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
27610 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27620 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
27630 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
27640 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
27650 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
27660 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
27670 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
27680 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
27690 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
276a0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
276b0 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
276c0 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
276d0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
276e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
276f0 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
27700 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
27710 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
27720 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
27730 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
27740 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
27750 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
27760 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
27770 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
27780 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
27790 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
277a0 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
277b0 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
277c0 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
277d0 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
277e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
277f0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
27800 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
27810 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
27830 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
27840 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
27850 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
27860 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
27870 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
27880 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
27890 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
278a0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
278b0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
278c0 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
278d0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
278e0 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
278f0 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
27900 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
27910 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
27920 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
27930 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
27940 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
27950 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
27960 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
27970 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
27980 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
27990 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
279a0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
279b0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
279c0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
279d0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
279e0 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
279f0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
27a00 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
27a10 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
27a20 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
27a30 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
27a40 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
27a50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27a60 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
27a70 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27a80 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
27a90 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
27aa0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
27ab0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
27ac0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
27ad0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27ae0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
27af0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
27b00 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
27b10 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
27b20 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
27b30 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
27b40 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
27b50 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
27b60 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
27b70 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
27b80 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
27b90 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
27ba0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
27bb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
27bc0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
27bd0 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
27be0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27bf0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
27c00 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
27c10 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
27c20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
27c30 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
27c40 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
27c50 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
27c60 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
27c70 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
27c80 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
27c90 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
27ca0 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
27cb0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
27cc0 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
27cd0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
27ce0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
27cf0 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
27d00 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
27d10 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
27d20 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
27d30 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
27d40 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
27d50 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
27d60 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
27d70 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
27d80 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
27d90 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
27da0 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
27db0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
27dc0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
27dd0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
27de0 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
27df0 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
27e00 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
27e10 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
27e20 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
27e30 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
27e40 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
27e50 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
27e60 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
27e70 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
27e80 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
27e90 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
27ea0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
27eb0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
27ec0 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
27ed0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
27ee0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
27ef0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
27f00 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
27f10 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
27f20 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
27f30 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
27f40 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
27f50 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
27f60 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
27f70 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
27f80 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
27f90 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
27fa0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
27fb0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
27fc0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
27fd0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
27fe0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
27ff0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
28000 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
28010 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
28020 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
28030 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
28040 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
28050 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
28060 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
28070 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
28080 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
28090 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
280a0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
280b0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
280c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
280d0 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
280e0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
280f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
28100 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
28110 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
28120 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
28130 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
28150 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
28160 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
28170 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
28180 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
28190 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
281a0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
281b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
281c0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
281d0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
281e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
281f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
28200 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
28210 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
28220 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28230 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
28240 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
28250 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
28260 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
28270 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
28280 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
28290 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
282a0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
282b0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
282c0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
282d0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
282e0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
282f0 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
28300 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
28310 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
28320 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
28330 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
28340 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
28350 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
28360 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
28370 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
28380 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
28390 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
283a0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
283b0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
283c0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
283d0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
283e0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
283f0 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
28400 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
28410 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
28420 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
28430 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
28440 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
28450 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
28460 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
28470 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
28480 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
28490 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
284a0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
284b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
284c0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
284d0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
284e0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
284f0 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
28500 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
28510 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
28520 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
28530 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
28540 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
28550 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
28560 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
28570 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
28580 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
28590 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
285a0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
285b0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
285c0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
285d0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
285e0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
285f0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
28600 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
28610 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
28620 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
28630 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
28640 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
28650 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
28660 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
28670 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
28680 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
28690 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
286a0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
286b0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
286c0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
286d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
286e0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
286f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28700 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
28710 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
28720 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28730 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
28740 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
28750 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
28760 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
28770 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
28780 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
28790 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
287a0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
287b0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
287c0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
287d0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
287e0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
287f0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
28800 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
28810 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
28820 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
28830 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
28840 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
28850 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
28860 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
28870 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
28880 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
28890 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
288a0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
288b0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
288c0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
288d0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
288e0 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
288f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
28900 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
28910 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28920 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
28930 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
28940 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
28950 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
28960 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
28970 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
28980 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
28990 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
289a0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
289b0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
289c0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
289d0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
289e0 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
289f0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
28a00 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
28a10 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
28a20 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
28a30 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
28a40 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
28a50 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
28a60 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
28a70 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
28a80 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
28a90 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
28aa0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
28ab0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
28ac0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
28ad0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
28ae0 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
28af0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
28b00 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
28b10 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
28b20 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
28b30 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
28b40 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
28b50 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
28b60 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
28b70 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
28b80 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
28b90 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
28ba0 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
28bb0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
28bc0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
28bd0 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
28be0 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
28bf0 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
28c00 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
28c10 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
28c20 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
28c30 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
28c40 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
28c50 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
28c60 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
28c70 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
28c80 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
28c90 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
28ca0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
28cb0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
28cc0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
28cd0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
28ce0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
28cf0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
28d00 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
28d10 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
28d20 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
28d30 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
28d40 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
28d50 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
28d60 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
28d70 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
28d80 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
28d90 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
28da0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
28db0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
28dc0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
28dd0 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
28de0 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
28df0 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
28e00 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
28e10 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
28e20 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
28e30 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
28e40 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
28e50 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
28e60 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
28e70 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
28e80 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
28e90 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
28ea0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
28eb0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
28ec0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
28ed0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
28ee0 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
28ef0 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
28f00 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
28f10 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
28f20 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
28f30 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
28f40 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
28f50 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
28f60 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
28f70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
28f80 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
28f90 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
28fa0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
28fb0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
28fc0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
28fd0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
28fe0 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
28ff0 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
29000 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
29010 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
29020 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
29030 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
29040 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
29050 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29060 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
29070 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
29080 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
29090 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
290a0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
290b0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
290c0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
290d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
290e0 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
290f0 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
29100 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
29110 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
29120 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
29130 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
29140 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
29150 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
29160 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
29170 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
29180 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
29190 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
291a0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
291b0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
291c0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
291d0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
291e0 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
291f0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
29200 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
29210 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
29220 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
29230 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
29240 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
29250 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
29260 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
29270 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
29280 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
29290 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
292a0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
292b0 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
292c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
292d0 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
292e0 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
292f0 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
29300 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
29310 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
29320 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
29330 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
29340 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
29350 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
29360 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
29370 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
29380 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
29390 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
293a0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
293b0 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
293c0 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
293d0 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
293e0 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
293f0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
29400 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
29410 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
29420 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
29430 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
29440 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
29450 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
29460 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
29470 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
29480 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
29490 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
294a0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
294b0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
294c0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
294d0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
294e0 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
294f0 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
29500 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
29510 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
29520 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
29530 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
29540 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
29550 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
29560 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
29570 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
29580 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
29590 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
295a0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
295b0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
295c0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
295d0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
295e0 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
295f0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
29600 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
29610 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
29620 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
29630 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
29640 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
29650 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
29660 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
29670 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
29680 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
29690 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
296a0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
296b0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
296c0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
296d0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
296e0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
296f0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
29700 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
29710 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
29720 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
29730 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
29740 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
29750 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
29760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29770 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
29780 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
29790 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
297a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
297b0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
297c0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
297d0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
297e0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
297f0 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
29800 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
29810 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
29820 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
29830 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
29840 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
29850 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
29860 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
29870 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29880 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
29890 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
298a0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
298b0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
298c0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
298d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
298e0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
298f0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
29900 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
29910 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
29920 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
29930 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
29940 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
29950 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
29960 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
29970 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
29980 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
29990 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
299a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
299b0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
299c0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
299d0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
299e0 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
299f0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
29a00 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
29a10 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
29a20 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
29a30 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
29a40 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
29a50 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
29a60 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
29a70 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
29a80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
29a90 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
29aa0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
29ab0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
29ac0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
29ad0 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
29ae0 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
29af0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
29b00 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
29b10 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
29b20 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
29b30 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
29b40 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
29b50 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
29b60 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
29b70 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
29b80 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
29b90 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
29ba0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
29bb0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
29bc0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
29bd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
29be0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
29bf0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
29c00 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
29c10 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
29c20 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
29c30 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
29c40 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
29c50 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
29c60 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
29c70 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
29c80 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
29c90 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
29ca0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
29cb0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
29cc0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
29cd0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
29ce0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
29cf0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
29d00 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
29d10 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
29d20 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
29d30 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
29d40 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
29d50 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
29d60 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
29d70 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
29d80 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
29d90 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
29da0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
29db0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
29dc0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
29dd0 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
29de0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
29df0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
29e00 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
29e10 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
29e20 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
29e30 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
29e40 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
29e50 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
29e60 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
29e70 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
29e80 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
29e90 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
29ea0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
29eb0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
29ec0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
29ed0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
29ee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
29ef0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
29f00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
29f10 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
29f20 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
29f30 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
29f40 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
29f50 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
29f60 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
29f70 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
29f80 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
29f90 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
29fa0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
29fb0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
29fc0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
29fd0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
29fe0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
29ff0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2a000 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2a010 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2a020 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2a030 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2a040 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a050 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2a060 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2a070 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2a080 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2a090 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2a0a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a0b0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2a0c0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2a0d0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2a0e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2a0f0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2a100 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2a110 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2a120 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2a130 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2a140 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2a150 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2a160 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2a170 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2a180 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2a190 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2a1a0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2a1b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2a1c0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2a1d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2a1e0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2a1f0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2a200 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2a210 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2a220 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2a230 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2a240 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2a250 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2a260 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2a270 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2a280 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2a290 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2a2a0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2a2b0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2a2c0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2a2d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2a2e0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2a2f0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2a300 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2a310 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2a320 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2a330 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2a340 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2a350 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2a360 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a370 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2a380 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2a390 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2a3a0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2a3b0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2a3c0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2a3d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2a3e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a3f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2a400 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2a410 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2a420 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2a430 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2a440 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2a450 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2a460 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2a470 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2a480 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2a490 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a4a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2a4b0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2a4c0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2a4d0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2a4e0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2a4f0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2a500 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2a510 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2a520 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2a530 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2a540 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2a550 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2a560 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2a570 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2a580 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2a590 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2a5a0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2a5b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2a5c0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2a5d0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2a5e0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2a5f0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2a600 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2a610 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2a620 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2a630 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2a640 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2a650 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2a660 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2a670 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2a680 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2a690 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2a6a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a6b0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2a6c0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2a6d0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2a6e0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2a6f0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2a700 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2a710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2a720 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2a730 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2a740 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2a750 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2a760 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2a770 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2a780 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2a790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a7a0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2a7b0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2a7c0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2a7d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2a7e0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2a7f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2a800 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2a810 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2a820 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2a830 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2a840 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2a850 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2a860 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2a870 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2a880 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2a890 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2a8a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2a8b0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2a8c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2a8d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2a8e0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2a8f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2a900 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2a910 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2a920 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2a930 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2a940 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2a950 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2a960 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2a970 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2a980 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2a990 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2a9a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2a9b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2a9c0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2a9d0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2a9e0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2a9f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2aa00 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2aa10 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2aa20 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2aa30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2aa40 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2aa50 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2aa60 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2aa70 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2aa80 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2aa90 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2aaa0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2aab0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2aac0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2aad0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2aae0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2aaf0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2ab00 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2ab10 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2ab20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2ab30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2ab40 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2ab50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2ab60 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2ab70 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2ab80 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2ab90 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2aba0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2abb0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2abc0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2abd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2abe0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2abf0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2ac00 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2ac10 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2ac20 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2ac30 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2ac40 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2ac50 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2ac60 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2ac70 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2ac80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ac90 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2aca0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2acb0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2acc0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2acd0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2ace0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2acf0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2ad00 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2ad10 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2ad20 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2ad30 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2ad40 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2ad50 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2ad60 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2ad70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ad80 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2ad90 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2ada0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2adb0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2adc0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2add0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2ade0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2adf0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2ae00 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2ae10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2ae20 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2ae30 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2ae40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2ae50 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2ae60 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2ae70 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2ae80 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2ae90 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2aea0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2aeb0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2aec0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2aed0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2aee0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2aef0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2af00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2af10 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2af20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2af30 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2af40 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2af50 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2af60 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2af70 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2af80 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2af90 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2afa0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2afb0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2afc0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2afd0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2afe0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2aff0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2b000 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2b010 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2b020 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2b030 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2b040 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2b050 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2b060 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2b070 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2b080 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2b090 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2b0a0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2b0b0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2b0c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2b0d0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2b0e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2b0f0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2b100 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2b110 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2b120 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2b130 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2b140 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2b150 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2b160 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2b170 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2b180 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2b190 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2b1a0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2b1b0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2b1c0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
2b1d0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
2b1e0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2b1f0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
2b200 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2b210 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
2b220 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2b230 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2b240 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2b250 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
2b260 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2b270 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
2b280 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2b290 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
2b2a0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
2b2b0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2b2c0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2b2d0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2b2e0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2b2f0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2b300 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2b310 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2b320 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
2b330 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2b340 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2b350 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
2b360 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2b370 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2b380 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
2b390 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2b3a0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2b3b0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2b3c0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
2b3d0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2b3e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2b3f0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2b400 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
2b410 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2b420 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2b430 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2b440 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
2b450 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
2b460 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2b470 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2b480 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2b490 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2b4a0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2b4b0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2b4c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2b4d0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2b4e0 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2b4f0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2b500 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2b510 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2b520 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2b530 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2b540 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2b550 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2b560 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2b570 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2b580 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2b590 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2b5a0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2b5b0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2b5c0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2b5d0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2b5e0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2b5f0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2b600 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2b610 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2b620 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2b630 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2b640 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2b650 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2b660 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2b670 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2b680 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2b690 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2b6a0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2b6b0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2b6c0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2b6d0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2b6e0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2b6f0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2b700 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2b710 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2b720 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2b730 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2b740 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2b750 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2b760 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2b770 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2b780 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2b790 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2b7a0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2b7b0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2b7c0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2b7d0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2b7e0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2b7f0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2b800 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2b810 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2b820 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2b830 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2b840 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2b850 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2b860 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2b870 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2b880 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2b890 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2b8a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b8b0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2b8c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b8d0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2b8e0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2b8f0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2b900 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2b910 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2b920 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2b930 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2b940 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2b950 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2b960 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2b970 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2b980 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2b990 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2b9a0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2b9b0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2b9c0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2b9d0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2b9e0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2b9f0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2ba00 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2ba10 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2ba20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2ba30 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2ba40 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2ba50 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2ba60 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2ba70 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2ba80 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2ba90 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2baa0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2bab0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2bac0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2bad0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2bae0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2baf0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2bb00 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2bb10 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2bb20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2bb30 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2bb40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2bb50 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2bb60 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2bb70 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2bb80 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2bb90 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2bba0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2bbb0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2bbc0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2bbd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2bbe0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2bbf0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2bc00 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2bc10 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2bc20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2bc30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2bc40 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2bc50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2bc60 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2bc70 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2bc80 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2bc90 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2bca0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2bcb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2bcc0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2bcd0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2bce0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2bcf0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2bd00 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2bd10 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2bd20 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2bd30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2bd40 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2bd50 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2bd60 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2bd70 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2bd80 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2bd90 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2bda0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2bdb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bdc0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2bdd0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2bde0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2bdf0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2be00 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2be10 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2be20 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2be30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2be40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2be50 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2be60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2be70 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2be80 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2be90 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2bea0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2beb0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2bec0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2bed0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2bee0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2bef0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
2bf00 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2bf10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bf20 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2bf30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2bf40 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2bf50 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2bf60 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2bf70 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2bf80 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2bf90 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2bfa0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2bfb0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2bfc0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2bfd0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2bfe0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2bff0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2c000 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2c010 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2c020 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2c030 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2c040 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2c050 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2c060 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2c070 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
2c080 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2c090 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2c0a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2c0b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c0c0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
2c0d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2c0e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2c0f0 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
2c100 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2c110 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
2c120 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
2c130 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c140 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2c150 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2c160 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2c170 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2c180 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2c190 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2c1a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c1b0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
2c1c0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2c1d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c1e0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2c1f0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2c200 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2c210 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
2c220 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c230 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2c240 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2c250 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c260 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2c270 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
2c280 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
2c290 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c2a0 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
2c2b0 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
2c2c0 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
2c2d0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2c2e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c2f0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2c300 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2c310 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2c320 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2c330 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2c340 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2c350 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2c360 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
2c370 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
2c380 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
2c390 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
2c3a0 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
2c3b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c3c0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
2c3d0 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
2c3e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2c3f0 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
2c400 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
2c410 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
2c420 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
2c430 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
2c440 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
2c450 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2c460 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2c470 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c480 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
2c490 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
2c4a0 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
2c4b0 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
2c4c0 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
2c4d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c4e0 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
2c4f0 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
2c500 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
2c510 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
2c520 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2c530 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
2c540 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
2c550 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
2c560 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
2c570 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
2c580 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
2c590 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
2c5a0 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
2c5b0 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
2c5c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2c5d0 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
2c5e0 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
2c5f0 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
2c600 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
2c610 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
2c620 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c630 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
2c640 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
2c650 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
2c660 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
2c670 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
2c680 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
2c690 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
2c6a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
2c6b0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
2c6c0 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
2c6d0 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
2c6e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
2c6f0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2c700 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
2c710 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
2c720 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
2c730 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
2c740 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
2c750 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
2c760 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
2c770 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
2c780 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2c790 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c7a0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
2c7b0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2c7c0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2c7d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2c7e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2c7f0 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2c800 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c810 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2c820 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2c830 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2c840 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2c850 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
2c860 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2c870 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2c880 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2c890 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2c8a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2c8b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2c8c0 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2c8d0 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2c8e0 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2c8f0 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2c900 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2c910 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
2c920 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2c930 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
2c940 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
2c950 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
2c960 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
2c970 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2c980 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
2c990 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2c9a0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2c9b0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2c9c0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2c9d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
2c9e0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2c9f0 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
2ca00 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
2ca10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2ca20 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
2ca30 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
2ca40 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
2ca50 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2ca60 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2ca70 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
2ca80 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2ca90 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2caa0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2cab0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2cac0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2cad0 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2cae0 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
2caf0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2cb00 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2cb10 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
2cb20 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2cb30 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2cb40 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
2cb50 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
2cb60 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
2cb70 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
2cb80 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
2cb90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cba0 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
2cbb0 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
2cbc0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2cbd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cbe0 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
2cbf0 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
2cc00 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
2cc10 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
2cc20 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
2cc30 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2cc40 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2cc50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
2cc60 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2cc70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2cc80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
2cc90 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
2cca0 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
2ccb0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
2ccc0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2ccd0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
2cce0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
2ccf0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2cd00 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
2cd10 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
2cd20 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
2cd30 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
2cd40 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2cd50 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
2cd60 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
2cd70 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
2cd80 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
2cd90 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
2cda0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
2cdb0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
2cdc0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
2cdd0 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
2cde0 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
2cdf0 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
2ce00 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
2ce10 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
2ce20 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
2ce30 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2ce40 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
2ce50 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2ce60 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2ce70 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
2ce80 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
2ce90 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
2cea0 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
2ceb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
2cec0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
2ced0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2cee0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
2cef0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2cf00 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
2cf10 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
2cf20 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
2cf30 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
2cf40 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
2cf50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2cf60 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2cf70 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2cf80 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
2cf90 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
2cfa0 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
2cfb0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
2cfc0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
2cfd0 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
2cfe0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
2cff0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2d000 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2d010 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
2d020 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
2d030 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
2d040 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
2d050 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
2d060 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
2d070 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
2d080 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
2d090 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
2d0a0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
2d0b0 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
2d0c0 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
2d0d0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2d0e0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2d0f0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
2d100 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2d110 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2d120 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2d130 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2d140 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
2d150 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
2d160 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
2d170 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2d180 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
2d190 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2d1a0 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
2d1b0 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
2d1c0 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
2d1d0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2d1e0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2d1f0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
2d200 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
2d210 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
2d220 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2d230 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
2d240 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
2d250 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2d260 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2d270 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
2d280 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
2d290 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
2d2a0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
2d2b0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
2d2c0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
2d2d0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
2d2e0 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69  Every SQL functi
2d2f0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2d300 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74  n must be able t
2d310 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55  o work.** with U
2d320 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
2d330 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
2d340 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
2d350 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
2d360 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
2d370 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
2d380 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
2d390 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2d3a0 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73   may.** invoke s
2d3b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d3c0 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
2d3d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d3e0 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
2d3f0 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
2d400 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2d410 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2d420 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
2d430 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e  extRep..** ^When
2d440 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2d450 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2d460 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
2d470 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
2d480 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
2d490 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
2d4a0 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
2d4b0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
2d4c0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
2d4d0 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
2d4e0 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
2d4f0 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
2d500 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
2d510 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
2d520 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
2d530 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2d540 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
2d550 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
2d560 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
2d570 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
2d580 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
2d590 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
2d5a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
2d5b0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
2d5c0 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
2d5d0 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
2d5e0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2d5f0 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  a()].)^.**.** ^T
2d600 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74  he sixth, sevent
2d610 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72  h and eighth par
2d620 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
2d630 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2d640 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
2d650 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
2d660 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
2d670 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2d680 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2d690 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
2d6a0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2d6b0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2d6c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2d6d0 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2d6e0 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
2d6f0 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62   pointers must b
2d700 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2d710 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2d720 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2d730 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
2d740 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2d750 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2d760 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
2d770 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
2d780 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75   NULL pointer mu
2d790 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  st be passed for
2d7a0 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
2d7b0 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
2d7c0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
2d7d0 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
2d7e0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  s NULL pointers 
2d7f0 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
2d800 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
2d810 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
2d820 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
2d830 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
2d840 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2d850 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
2d860 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
2d870 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2d880 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2d890 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
2d8a0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2d8b0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
2d8c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
2d8d0 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
2d8e0 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
2d8f0 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
2d900 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d910 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
2d920 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
2d930 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
2d940 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
2d950 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
2d960 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2d970 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
2d980 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
2d990 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
2d9a0 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
2d9b0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
2d9c0 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
2d9d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
2d9e0 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
2d9f0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2da00 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
2da10 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
2da20 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2da30 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
2da40 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
2da50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
2da60 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2da70 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2da80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2da90 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2daa0 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2dab0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2dac0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2dad0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2dae0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2daf0 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2db00 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2db10 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
2db20 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
2db30 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
2db40 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
2db50 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
2db60 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
2db70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
2db80 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
2db90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2dba0 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
2dbb0 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
2dbc0 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
2dbd0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2dbe0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2dbf0 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
2dc00 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
2dc10 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2dc20 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2dc30 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
2dc40 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
2dc50 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
2dc60 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
2dc70 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
2dc80 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2dc90 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2dca0 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
2dcb0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2dcc0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2dcd0 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
2dce0 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
2dcf0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
2dd00 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2dd10 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2dd20 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2dd30 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
2dd40 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
2dd50 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
2dd60 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
2dd70 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
2dd80 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
2dd90 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2dda0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
2ddb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ddc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2ddd0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
2dde0 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
2ddf0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
2de00 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
2de10 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
2de20 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
2de30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
2de40 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
2de50 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
2de60 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
2de70 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
2de80 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2de90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
2dea0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
2deb0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2dec0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2ded0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2dee0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2def0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2df00 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2df10 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2df20 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2df30 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2df40 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2df50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2df60 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2df70 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2df80 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2df90 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2dfa0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2dfb0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2dfc0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
2dfd0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
2dfe0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2dff0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2e000 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2e010 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2e020 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2e030 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2e040 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2e050 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2e060 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2e070 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2e080 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2e090 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2e0a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2e0b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2e0c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2e0d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2e0e0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2e0f0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2e100 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2e110 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2e120 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2e130 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2e140 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2e150 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2e160 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e170 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2e180 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2e190 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2e1a0 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
2e1b0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2e1c0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2e1d0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
2e1e0 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
2e1f0 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2e200 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2e210 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2e220 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2e230 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2e240 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2e250 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2e260 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2e270 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2e280 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2e290 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2e2a0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2e2b0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2e2c0 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2e2d0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2e2e0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2e2f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2e300 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2e310 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2e320 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2e330 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2e340 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2e350 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
2e360 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2e370 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
2e380 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e390 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
2e3a0 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
2e3b0 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
2e3c0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
2e3d0 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
2e3e0 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
2e3f0 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
2e400 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
2e410 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
2e420 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
2e430 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
2e440 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
2e450 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
2e460 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
2e470 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
2e480 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2e490 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
2e4a0 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
2e4b0 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
2e4c0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
2e4d0 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
2e4e0 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
2e4f0 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
2e500 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
2e510 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
2e520 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2e530 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
2e540 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
2e550 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
2e560 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2e570 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
2e580 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
2e590 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2e5a0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2e5b0 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
2e5c0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2e5d0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
2e5e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
2e5f0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2e600 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
2e610 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
2e620 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
2e630 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
2e640 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
2e650 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2e660 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
2e670 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
2e680 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2e690 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
2e6a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
2e6b0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2e6c0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
2e6d0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
2e6e0 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a  rameter Values.*
2e6f0 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
2e700 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
2e710 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
2e720 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2e730 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
2e740 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
2e750 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
2e760 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
2e770 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
2e780 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
2e790 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
2e7a0 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
2e7b0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
2e7c0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
2e7d0 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
2e7e0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
2e7f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e800 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2e810 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e820 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
2e830 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
2e840 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2e850 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2e860 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
2e870 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
2e880 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
2e890 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
2e8a0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
2e8b0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
2e8c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2e8d0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
2e8e0 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
2e8f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
2e900 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
2e910 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
2e920 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
2e930 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2e940 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
2e950 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
2e960 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2e970 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
2e980 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2e990 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
2e9a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e9b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2e9c0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
2e9d0 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
2e9e0 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
2e9f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ea00 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
2ea10 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
2ea20 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
2ea30 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2ea40 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
2ea50 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
2ea60 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
2ea70 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
2ea80 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
2ea90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
2eaa0 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
2eab0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2eac0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
2ead0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
2eae0 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
2eaf0 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
2eb00 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
2eb10 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
2eb20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
2eb30 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
2eb40 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
2eb50 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2eb60 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
2eb70 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
2eb80 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
2eb90 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
2eba0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
2ebb0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2ebc0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
2ebd0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
2ebe0 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
2ebf0 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
2ec00 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
2ec10 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
2ec20 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
2ec30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
2ec40 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
2ec50 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2ec60 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
2ec70 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
2ec80 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
2ec90 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
2eca0 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
2ecb0 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
2ecc0 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
2ecd0 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
2ece0 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
2ecf0 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
2ed00 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
2ed10 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
2ed20 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
2ed30 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
2ed40 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
2ed50 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
2ed60 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
2ed70 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
2ed80 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
2ed90 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
2eda0 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
2edb0 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
2edc0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2edd0 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
2ede0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
2edf0 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
2ee00 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
2ee10 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
2ee20 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
2ee30 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
2ee40 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
2ee50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2ee60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2ee70 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
2ee80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2ee90 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
2eea0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
2eeb0 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
2eec0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2eed0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2eee0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2eef0 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
2ef00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2ef10 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2ef20 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2ef30 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
2ef40 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
2ef50 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2ef60 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
2ef70 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
2ef80 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
2ef90 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
2efa0 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
2efb0 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
2efc0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2efd0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
2efe0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2eff0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2f000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f010 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2f020 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
2f030 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
2f040 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
2f050 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2f060 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2f070 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
2f080 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f090 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2f0a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
2f0b0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
2f0c0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
2f0d0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2f0e0 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
2f0f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2f100 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2f110 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
2f120 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2f130 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f140 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2f150 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f160 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2f170 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f180 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
2f190 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2f1a0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
2f1b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2f1c0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2f1d0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
2f1e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
2f1f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f200 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
2f210 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2f220 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
2f230 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
2f240 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2f250 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
2f260 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
2f270 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
2f280 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
2f290 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2f2a0 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
2f2b0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2f2c0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
2f2d0 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
2f2e0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2f2f0 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
2f300 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
2f310 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
2f320 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
2f330 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
2f340 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2f350 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
2f360 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
2f370 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2f380 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
2f390 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2f3a0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
2f3b0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2f3c0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
2f3d0 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
2f3e0 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
2f3f0 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
2f400 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2f410 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
2f420 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
2f430 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
2f440 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
2f450 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
2f460 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
2f470 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
2f480 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
2f490 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
2f4a0 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
2f4b0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
2f4c0 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
2f4d0 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
2f4e0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2f4f0 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
2f500 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
2f510 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
2f520 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
2f530 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
2f540 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
2f550 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2f560 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
2f570 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
2f580 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
2f590 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
2f5a0 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
2f5b0 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
2f5c0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2f5d0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2f5e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2f5f0 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73   if N is.** less
2f600 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
2f610 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
2f620 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65  emory allocate e
2f630 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
2f640 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
2f650 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
2f660 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
2f670 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2f680 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
2f690 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
2f6a0 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
2f6b0 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
2f6c0 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
2f6d0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
2f6e0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
2f6f0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
2f700 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2f710 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
2f720 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
2f730 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
2f740 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
2f750 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
2f760 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a  location.)^.**.*
2f770 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
2f780 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
2f790 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
2f7a0 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
2f7b0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2f7c0 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
2f7d0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
2f7e0 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
2f7f0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2f800 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
2f810 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
2f820 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
2f830 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
2f840 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
2f850 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2f860 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
2f870 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
2f880 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
2f890 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2f8a0 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
2f8b0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2f8c0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2f8d0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2f8e0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2f8f0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2f900 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2f910 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2f920 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2f930 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2f940 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
2f950 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
2f960 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
2f970 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
2f980 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
2f990 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f9a0 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
2f9b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2f9c0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
2f9d0 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
2f9e0 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
2f9f0 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
2fa00 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2fa10 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2fa20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2fa30 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2fa40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2fa50 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2fa60 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2fa70 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2fa80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2fa90 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
2faa0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2fab0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2fac0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2fad0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2fae0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2faf0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2fb00 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2fb10 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2fb20 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
2fb30 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
2fb40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2fb50 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2fb60 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
2fb70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fb80 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2fb90 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
2fba0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
2fbb0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
2fbc0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
2fbd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2fbe0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
2fbf0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2fc00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fc10 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2fc20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2fc30 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
2fc40 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
2fc50 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
2fc60 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
2fc70 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2fc80 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
2fc90 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
2fca0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
2fcb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2fcc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fcd0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
2fce0 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
2fcf0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
2fd00 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
2fd10 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
2fd20 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
2fd30 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
2fd40 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
2fd50 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
2fd60 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
2fd70 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
2fd80 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
2fd90 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2fda0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
2fdb0 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
2fdc0 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
2fdd0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
2fde0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
2fdf0 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
2fe00 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
2fe10 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
2fe20 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
2fe30 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
2fe40 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
2fe50 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
2fe60 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
2fe70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
2fe80 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2fe90 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
2fea0 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
2feb0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2fec0 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
2fed0 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
2fee0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
2fef0 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
2ff00 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
2ff10 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
2ff20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
2ff30 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
2ff40 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2ff50 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
2ff60 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
2ff70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
2ff80 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2ff90 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
2ffa0 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
2ffb0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
2ffc0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2ffd0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2ffe0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2fff0 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
30000 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
30010 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
30020 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
30030 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
30040 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
30050 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
30060 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30070 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20  unction. ^If no 
30080 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
30090 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
300a0 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
300b0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
300c0 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
300d0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
300e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
300f0 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
30100 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
30110 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
30120 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
30130 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
30140 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
30150 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
30160 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
30170 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
30180 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
30190 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
301a0 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
301b0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
301c0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
301d0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
301e0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
301f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30200 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
30210 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
30220 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
30230 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
30240 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
30250 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
30260 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e   destroyed..** ^
30270 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
30280 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
30290 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
302a0 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
302b0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
302c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
302d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
302e0 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
302f0 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
30300 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
30310 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
30320 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
30330 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
30340 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
30350 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
30360 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
30370 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
30380 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
30390 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
303a0 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
303b0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
303c0 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
303d0 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e  y time.  ^The on
303e0 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
303f0 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
30400 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
30410 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
30420 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
30430 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  pped..**.** ^(In
30440 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
30450 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
30460 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
30470 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
30480 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
30490 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
304a0 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
304b0 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
304c0 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
304d0 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  d [parameters].)
304e0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
304f0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
30500 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
30510 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
30520 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
30530 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
30540 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
30550 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
30560 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30570 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
30580 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
30590 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
305a0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
305b0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
305c0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
305d0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
305e0 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
305f0 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
30600 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
30610 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
30620 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
30630 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
30640 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
30650 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
30660 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
30670 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
30680 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
30690 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
306a0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
306b0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
306c0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
306d0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
306e0 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
306f0 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
30700 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
30710 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
30720 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
30730 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
30740 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
30750 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
30760 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
30770 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
30780 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
30790 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
307a0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
307b0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
307c0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
307d0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
307e0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
307f0 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
30800 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
30810 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
30820 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
30830 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
30840 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
30850 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
30860 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
30870 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
30880 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
30890 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
308a0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
308b0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
308c0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
308d0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
308e0 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
308f0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
30900 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
30910 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
30920 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
30930 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
30940 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
30950 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
30960 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
30970 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
30980 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
30990 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
309a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
309b0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
309c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
309d0 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
309e0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
309f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
30a00 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
30a10 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
30a20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
30a30 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
30a40 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
30a50 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
30a60 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
30a70 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
30a80 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
30a90 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
30aa0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
30ab0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
30ac0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
30ad0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
30ae0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30af0 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
30b00 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
30b10 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
30b20 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30b30 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
30b40 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
30b50 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
30b60 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
30b70 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
30b80 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
30b90 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
30ba0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
30bb0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
30bc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30bd0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
30be0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
30bf0 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
30c00 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
30c10 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30c20 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
30c30 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
30c40 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
30c50 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
30c60 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
30c70 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
30c80 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
30c90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30ca0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
30cb0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
30cc0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
30cd0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
30ce0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30cf0 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
30d00 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
30d10 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
30d20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
30d30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30d40 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30d50 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
30d60 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
30d70 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
30d80 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
30d90 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
30da0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
30db0 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
30dc0 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
30dd0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
30de0 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
30df0 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
30e00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
30e10 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
30e20 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
30e30 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
30e40 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
30e50 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
30e60 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
30e70 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
30e80 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
30e90 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
30ea0 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
30eb0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
30ec0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
30ed0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30ee0 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
30ef0 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
30f00 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
30f10 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
30f20 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
30f30 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
30f40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30f50 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
30f60 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
30f70 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
30f80 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
30f90 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
30fa0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
30fb0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
30fc0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
30fd0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
30fe0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30ff0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
31000 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
31010 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
31020 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
31030 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
31040 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
31050 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
31060 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
31070 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
31080 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
31090 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
310a0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
310b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
310c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
310d0 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
310e0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
310f0 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
31100 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
31110 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
31120 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
31130 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
31140 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
31150 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
31160 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
31170 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
31180 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31190 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
311a0 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
311b0 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
311c0 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
311d0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
311e0 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
311f0 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
31200 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
31210 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
31220 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
31230 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
31240 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31250 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
31260 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31270 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
31280 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
31290 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
312a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
312b0 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
312c0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
312d0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
312e0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
312f0 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
31300 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
31310 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
31320 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
31330 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
31340 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
31350 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
31360 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
31370 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
31380 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
31390 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
313a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
313b0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
313c0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
313d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
313e0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
313f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31400 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
31410 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
31420 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
31430 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
31440 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
31450 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31460 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
31470 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
31480 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
31490 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
314a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
314b0 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
314c0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
314d0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
314e0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
314f0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
31500 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
31510 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
31520 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
31530 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
31540 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31550 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
31560 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
31570 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31580 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
31590 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
315a0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
315b0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
315c0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
315d0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
315e0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
315f0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
31600 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
31610 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31620 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
31630 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
31640 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
31650 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
31660 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
31670 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
31680 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
31690 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
316a0 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
316b0 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  ly..** ^SQLite t
316c0 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
316d0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
316e0 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
316f0 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
31700 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
31710 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31720 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
31730 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
31740 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
31750 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
31760 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
31770 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
31780 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
31790 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
317a0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
317b0 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
317c0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
317d0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
317e0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
317f0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
31800 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
31810 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
31820 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
31830 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
31840 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
31850 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
31860 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
31870 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
31880 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
31890 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
318a0 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
318b0 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72  sult.  If the 3r
318c0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
318d0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
318e0 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20  n it.** must be 
318f0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20  the byte offset 
31900 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20  into the string 
31910 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
31920 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a  rminator would.*
31930 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20  * appear if the 
31940 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c  string where NUL
31950 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
31960 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
31970 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ers occur.** in 
31980 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20  the string at a 
31990 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74  byte offset that
319a0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68   is less than th
319b0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33  e value of the 3
319c0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  rd.** parameter,
319d0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
319e0 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  ing string will 
319f0 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
31a00 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a   NULs and the.**
31a10 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
31a20 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67  ssions operating
31a30 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68   on strings with
31a40 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
31a50 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
31a60 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
31a70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
31a80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31a90 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
31aa0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
31ab0 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
31ac0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
31ad0 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
31ae0 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
31af0 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
31b00 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
31b10 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
31b20 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
31b30 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
31b40 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
31b50 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
31b60 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
31b70 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
31b80 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
31b90 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
31ba0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
31bb0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
31bc0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
31bd0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
31be0 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
31bf0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
31c00 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
31c10 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
31c20 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
31c30 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
31c40 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
31c50 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
31c60 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
31c70 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
31c80 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
31c90 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
31ca0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
31cb0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
31cc0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
31cd0 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
31ce0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
31cf0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
31d00 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
31d10 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
31d20 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
31d30 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
31d40 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
31d50 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
31d60 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
31d70 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
31d80 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
31d90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
31da0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
31db0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
31dc0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
31dd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31de0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
31df0 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
31e00 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
31e10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31e20 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
31e30 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
31e40 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
31e50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
31e60 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
31e70 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
31e80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
31e90 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
31ea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
31eb0 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
31ec0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
31ed0 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
31ee0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
31ef0 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
31f00 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
31f10 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
31f20 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
31f30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31f40 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
31f50 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
31f60 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
31f70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31f80 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
31f90 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
31fa0 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
31fb0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
31fc0 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
31fd0 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
31fe0 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
31ff0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
32000 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
32010 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
32020 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
32030 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
32040 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
32050 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32060 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
32070 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
32080 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
32090 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
320a0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
320b0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
320c0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
320d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
320e0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
320f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32100 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32110 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
32120 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
32130 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
32140 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
32150 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32160 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
32170 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
32180 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32190 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
321a0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
321b0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
321c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
321d0 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
321e0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
321f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32200 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
32210 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
32220 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32230 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
32240 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32250 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
32260 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
32270 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32280 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
32290 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
322a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
322b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
322c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
322d0 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
322e0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
322f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32300 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
32310 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
32320 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
32330 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
32340 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32350 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
32360 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
32370 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
32380 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
32390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
323a0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
323b0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
323c0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
323d0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
323e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
323f0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
32400 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
32410 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
32420 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
32430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32440 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
32450 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
32460 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
32470 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
32480 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
32490 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
324a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
324b0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
324c0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
324d0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
324e0 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f  ctions add, remo
324f0 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20  ve, or modify a 
32500 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f  [collation] asso
32510 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
32520 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
32530 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
32540 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
32550 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
32560 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
32570 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20   collation is a 
32580 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
32590 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
325a0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
325b0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
325c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
325d0 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
325e0 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
325f0 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
32600 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32610 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
32620 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  * ^Collation nam
32630 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20  es that compare 
32640 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20  equal according 
32650 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e  to [sqlite3_strn
32660 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63  icmp()] are.** c
32670 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
32680 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
32690 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64  *.** ^(The third
326a0 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74   argument (eText
326b0 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  Rep) must be one
326c0 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
326d0 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  s:.** <ul>.** <l
326e0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  i> [SQLITE_UTF8]
326f0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
32700 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c  E_UTF16LE],.** <
32710 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
32720 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6BE],.** <li> [S
32730 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72  QLITE_UTF16], or
32740 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
32750 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e  _UTF16_ALIGNED].
32760 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  .** </ul>)^.** ^
32770 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  The eTextRep arg
32780 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73  ument determines
32790 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
327a0 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a   strings passed.
327b0 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ** to the collat
327c0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
327d0 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b  lback, xCallback
327e0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
327f0 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51  E_UTF16] and [SQ
32800 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
32810 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65  ED] values for e
32820 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65  TextRep.** force
32830 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55   strings to be U
32840 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65  TF16 with native
32850 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
32860 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
32870 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
32880 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66  e for eTextRep f
32890 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f  orces strings to
328a0 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20   begin.** on an 
328b0 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73  even byte addres
328c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  s..**.** ^The fo
328d0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70  urth argument, p
328e0 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69  Arg, is an appli
328f0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
32900 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
32910 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73  ed.** through as
32920 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
32930 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ent to the colla
32940 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
32950 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
32960 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
32970 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73  t, xCallback, is
32980 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
32990 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
329a0 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70  tion..** ^Multip
329b0 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  le collating fun
329c0 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65  ctions can be re
329d0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
329e0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
329f0 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65  .** with differe
32a00 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61  nt eTextRep para
32a10 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74  meters and SQLit
32a20 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68  e will use which
32a30 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ever.** function
32a40 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
32a50 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
32a60 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f  ta transformatio
32a70 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43  n..** ^If the xC
32a80 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
32a90 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
32aa0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
32ab0 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74  tion is.** delet
32ac0 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63  ed.  ^When all c
32ad0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
32ae0 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61  ns having the sa
32af0 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65  me name are dele
32b00 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c  ted,.** that col
32b10 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  lation is no lon
32b20 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a  ger usable..**.*
32b30 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  * ^The collating
32b40 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
32b50 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
32b60 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  th a copy of the
32b70 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63   pArg .** applic
32b80 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
32b90 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20  er and with two 
32ba0 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65  strings in the e
32bb0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
32bc0 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78  d.** by the eTex
32bd0 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20  tRep argument.  
32be0 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
32bf0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75  nction must retu
32c00 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  rn an.** integer
32c10 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76   that is negativ
32c20 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69  e, zero, or posi
32c30 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66  tive.** if the f
32c40 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
32c50 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
32c60 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
32c70 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a  han the second,.
32c80 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
32c90 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75    A collating fu
32ca0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61  nction must alwa
32cb0 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
32cc0 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
32cd0 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
32ce0 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
32cf0 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
32d00 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
32d10 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
32d20 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
32d30 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
32d40 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
32d50 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
32d60 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
32d70 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
32d80 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
32d90 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
32da0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
32db0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
32dc0 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
32dd0 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
32de0 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
32df0 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
32e00 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
32e10 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
32e20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
32e30 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
32e40 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
32e50 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
32e60 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
32e70 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
32e80 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
32e90 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
32ea0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
32eb0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
32ec0 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
32ed0 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
32ee0 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
32ef0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
32f00 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
32f10 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
32f20 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
32f30 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
32f40 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
32f50 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
32f60 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
32f70 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
32f80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32f90 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
32fa0 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
32fb0 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
32fc0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
32fd0 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
32fe0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
32ff0 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
33000 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
33010 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
33020 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
33030 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
33040 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
33050 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
33060 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
33070 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
33080 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
33090 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
330a0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
330b0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
330c0 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
330d0 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
330e0 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
330f0 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
33100 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33110 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
33120 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
33130 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
33140 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
33150 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33160 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
33170 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
33180 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
33190 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
331a0 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
331b0 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
331c0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
331d0 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
331e0 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
331f0 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
33200 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
33210 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
33220 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
33230 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
33240 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
33250 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
33260 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
33270 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
33280 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
33290 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
332a0 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
332b0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
332c0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
332d0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
332e0 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
332f0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33300 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
33310 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
33320 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
33330 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
33340 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
33350 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
33360 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
33370 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
33380 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
33390 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
333a0 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
333b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
333c0 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
333d0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
333e0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
333f0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
33400 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
33410 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
33420 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
33430 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
33440 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
33450 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
33460 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
33470 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
33480 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
33490 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
334a0 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
334b0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
334c0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
334d0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
334e0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
334f0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
33500 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33510 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
33520 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
33530 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
33540 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
33550 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
33560 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
33570 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
33580 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
33590 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
335a0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
335b0 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
335c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
335d0 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
335e0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
335f0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
33600 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
33610 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
33620 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
33630 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
33640 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
33650 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33660 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
33670 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
33680 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
33690 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
336a0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
336b0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
336c0 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
336d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
336e0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
336f0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
33700 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
33710 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
33720 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
33730 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
33740 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
33750 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
33760 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
33770 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
33780 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
33790 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
337a0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
337b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
337c0 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
337d0 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
337e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
337f0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33800 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
33810 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33820 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
33830 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
33840 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
33850 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
33860 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
33870 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
33880 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
33890 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
338a0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
338b0 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
338c0 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
338d0 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
338e0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
338f0 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
33900 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
33910 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
33920 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
33930 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
33940 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
33950 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
33960 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
33970 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
33980 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
33990 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
339a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
339b0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
339c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
339d0 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
339e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
339f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33a00 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
33a10 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33a20 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
33a30 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
33a40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
33a50 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
33a60 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
33a70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
33a80 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
33a90 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
33aa0 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
33ab0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
33ac0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
33ad0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
33ae0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
33af0 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
33b00 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
33b10 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
33b20 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
33b30 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
33b40 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
33b50 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
33b60 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
33b70 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
33b80 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
33b90 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
33ba0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
33bb0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
33bc0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33bd0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
33be0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
33bf0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
33c00 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
33c10 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
33c20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
33c30 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
33c40 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
33c50 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
33c60 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
33c70 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
33c80 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
33c90 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
33ca0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
33cb0 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
33cc0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
33cd0 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
33ce0 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
33cf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
33d00 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
33d10 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
33d20 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
33d30 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
33d40 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
33d50 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
33d60 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
33d70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33d80 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
33d90 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
33da0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
33db0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
33dc0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
33dd0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
33de0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
33df0 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
33e00 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
33e10 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
33e20 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
33e30 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
33e40 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
33e50 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
33e60 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
33e70 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
33e80 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
33e90 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
33ea0 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
33eb0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
33ec0 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
33ed0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
33ee0 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
33ef0 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
33f00 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
33f10 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
33f20 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
33f30 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
33f40 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
33f50 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
33f60 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
33f70 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
33f80 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
33f90 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
33fa0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
33fb0 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
33fc0 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
33fd0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
33fe0 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
33ff0 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
34000 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
34010 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
34020 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
34030 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
34040 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
34050 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
34060 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
34070 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
34080 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
34090 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
340a0 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
340b0 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
340c0 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
340d0 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
340e0 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
340f0 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
34100 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
34110 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
34120 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
34130 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
34140 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
34150 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
34160 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
34170 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
34180 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
34190 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
341a0 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
341b0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
341c0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
341d0 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
341e0 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
341f0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
34200 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
34210 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
34220 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
34230 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
34240 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
34250 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
34260 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
34270 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
34280 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
34290 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
342a0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
342b0 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
342c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
342d0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
342e0 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
342f0 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
34300 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
34310 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
34320 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
34330 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
34340 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
34350 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
34360 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
34370 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
34380 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
34390 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
343a0 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
343b0 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
343c0 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
343d0 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
343e0 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
343f0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
34400 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
34410 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
34420 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
34430 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
34440 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
34450 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
34460 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
34470 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
34480 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
34490 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
344a0 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
344b0 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
344c0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
344d0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
344e0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
344f0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
34500 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
34510 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
34520 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
34530 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
34540 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
34550 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
34560 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
34570 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
34580 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
34590 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
345a0 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
345b0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
345c0 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
345d0 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
345e0 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
345f0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
34600 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
34610 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
34620 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
34630 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
34640 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
34650 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
34660 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
34670 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
34680 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
34690 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
346a0 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
346b0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
346c0 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
346d0 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
346e0 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
346f0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
34700 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
34710 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
34720 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
34730 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
34740 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
34750 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
34760 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
34770 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
34780 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
34790 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
347a0 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
347b0 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
347c0 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
347d0 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
347e0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
347f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
34800 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
34810 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
34820 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
34830 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
34840 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
34850 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
34860 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
34870 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
34880 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
34890 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
348a0 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
348b0 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
348c0 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
348d0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
348e0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
348f0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
34900 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
34910 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
34920 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
34930 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
34940 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
34950 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
34960 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
34970 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
34980 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
34990 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
349a0 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
349b0 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
349c0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
349d0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
349e0 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
349f0 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
34a00 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
34a10 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
34a20 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
34a30 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
34a40 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
34a50 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
34a60 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
34a70 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
34a80 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
34a90 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
34aa0 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
34ab0 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
34ac0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
34ad0 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
34ae0 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
34af0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
34b00 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
34b10 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
34b20 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
34b30 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
34b40 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
34b50 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
34b60 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
34b70 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
34b80 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
34b90 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
34ba0 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
34bb0 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
34bc0 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
34bd0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
34be0 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
34bf0 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
34c00 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
34c10 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
34c20 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
34c30 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
34c40 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
34c50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34c60 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
34c70 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
34c80 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
34c90 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
34ca0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
34cb0 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
34cc0 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
34cd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
34ce0 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
34cf0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
34d00 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
34d10 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
34d20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
34d30 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
34d40 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
34d50 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
34d60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
34d70 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
34d80 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
34d90 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
34da0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
34db0 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
34dc0 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
34dd0 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
34de0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
34df0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
34e00 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
34e10 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
34e20 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
34e30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34e40 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46 69  F: Return The Fi
34e50 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74  lename For A Dat
34e60 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
34e70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34e80 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28  te3_db_filename(
34e90 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  D,N) interface r
34ea0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
34eb0 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a   to a filename.*
34ec0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
34ed0 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20  h database N of 
34ee0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e  connection D.  ^
34ef0 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  The main databas
34f00 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68  e file.** has th
34f10 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20  e name "main".  
34f20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61  If there is no a
34f30 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
34f40 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61   N on the databa
34f50 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
34f60 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61   D, or if databa
34f70 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72  se N is a tempor
34f80 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79  ary or in-memory
34f90 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a   database, then.
34fa0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
34fb0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
34fc0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61  *.** ^The filena
34fd0 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  me returned by t
34fe0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
34ff0 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68  the output of th
35000 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61  e.** xFullPathna
35010 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  me method of the
35020 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68   [VFS].  ^In oth
35030 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69  er words, the fi
35040 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62  lename.** will b
35050 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  e an absolute pa
35060 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20  thname, even if 
35070 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65  the filename use
35080 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65  d.** to open the
35090 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e   database origin
350a0 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f  ally was a URI o
350b0 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e  r relative pathn
350c0 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ame..*/.const ch
350d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66  ar *sqlite3_db_f
350e0 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20  ilename(sqlite3 
350f0 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  *db, const char 
35100 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  *zDbName);../*.*
35110 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
35120 72 6d 69 6e 65 20 69 66 20 61 20 64 61 74 61 62  rmine if a datab
35130 61 73 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79  ase is read-only
35140 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35150 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28  te3_db_readonly(
35160 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  D,N) interface r
35170 65 74 75 72 6e 73 20 31 20 69 66 20 74 68 65 20  eturns 1 if the 
35180 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66  database N.** of
35190 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73   connection D is
351a0 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66   read-only, 0 if
351b0 20 69 74 20 69 73 20 72 65 61 64 2f 77 72 69 74   it is read/writ
351c0 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20 69 73  e, or -1 if N is
351d0 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d 65   not.** the name
351e0 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 6f   of a database o
351f0 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  n connection D..
35200 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
35210 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  b_readonly(sqlit
35220 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68  e3 *db, const ch
35230 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f  ar *zDbName);../
35240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
35250 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
35260 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
35270 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
35280 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
35290 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
352a0 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
352b0 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a  atement] after.*
352c0 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74  * pStmt associat
352d0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
352e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
352f0 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d  ] pDb.  ^If pStm
35300 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
35310 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
35320 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
35330 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
35340 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35350 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
35360 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
35370 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
35380 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61  b.  ^If no prepa
35390 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
353a0 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
353b0 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
353c0 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65  s routine, it re
353d0 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  turns NULL..**.*
353e0 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20  * The [database 
353f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e  connection] poin
35400 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20  ter D in a call 
35410 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e  to.** [sqlite3_n
35420 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d  ext_stmt(D,S)] m
35430 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20  ust refer to an 
35440 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  open database.**
35450 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
35460 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75  in particular mu
35470 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c  st not be a NULL
35480 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c   pointer..*/.sql
35490 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
354a0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
354b0 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
354c0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
354d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
354e0 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
354f0 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
35500 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
35510 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35520 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e  commit_hook() in
35530 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
35540 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
35550 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
35560 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
35570 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
35580 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69   [COMMIT | commi
35590 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  tted]..** ^Any c
355a0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
355b0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
355c0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
355d0 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
355e0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
355f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
35600 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
35610 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
35620 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
35630 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
35640 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
35650 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
35660 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
35670 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52  ransaction is [R
35680 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64  OLLBACK | rolled
35690 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20   back]..** ^Any 
356a0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
356b0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
356c0 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  to sqlite3_rollb
356d0 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  ack_hook().** fo
356e0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
356f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
35700 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
35710 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d   ^The pArg argum
35720 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
35730 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c  rough to the cal
35740 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68  lback..** ^If th
35750 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
35760 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
35770 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
35780 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
35790 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
357a0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
357b0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
357c0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
357d0 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e  t_hook(D,C,P) an
357e0 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  d sqlite3_rollba
357f0 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  ck_hook(D,C,P) f
35800 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75  unctions.** retu
35810 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  rn the P argumen
35820 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
35830 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20  ous call of the 
35840 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
35850 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
35860 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35870 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
35880 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
35890 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e  all for each fun
358a0 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a  ction on D..**.*
358b0 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64  * The commit and
358c0 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63   rollback hook c
358d0 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f 74  allbacks are not
358e0 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54   reentrant..** T
358f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c  he callback impl
35900 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
35910 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
35920 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
35930 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
35940 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
35950 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c   invoked the cal
35960 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69  lback.  Any acti
35970 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
35980 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
35990 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
359a0 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
359b0 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
359c0 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
359d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
359e0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
359f0 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a  red the commit.*
35a00 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  * or rollback ho
35a10 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ok in the first 
35a20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  place..** Note t
35a30 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  hat running any 
35a40 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74 65 6d  other SQL statem
35a50 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ents, including 
35a60 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
35a70 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20  s,.** or merely 
35a80 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
35a90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
35aa0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
35ab0 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  ()] will modify.
35ac0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
35ad0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
35ae0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
35af0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
35b00 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
35b10 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20   ^Registering a 
35b20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
35b30 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
35b40 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ack..**.** ^When
35b50 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
35b60 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
35b70 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  e returns zero, 
35b80 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  the [COMMIT].** 
35b90 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c  operation is all
35ba0 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65  owed to continue
35bb0 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20   normally.  ^If 
35bc0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a  the commit hook.
35bd0 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ** returns non-z
35be0 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43  ero, then the [C
35bf0 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72  OMMIT] is conver
35c00 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c  ted into a [ROLL
35c10 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  BACK]..** ^The r
35c20 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
35c30 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
35c40 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
35c50 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
35c60 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
35c70 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
35c80 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
35c90 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
35ca0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
35cb0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
35cc0 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
35cd0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
35ce0 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
35cf0 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  n.** rolled back
35d00 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
35d10 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
35d20 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
35d30 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
35d40 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
35d50 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
35d60 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
35d70 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  cur..** ^The rol
35d80 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
35d90 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
35da0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
35db0 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
35dc0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
35dd0 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
35de0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
35df0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
35e00 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
35e10 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
35e20 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  k()] interface..
35e30 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
35e40 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
35e50 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
35e60 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
35e70 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
35e80 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
35e90 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
35ea0 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
35eb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
35ec0 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
35ed0 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
35ee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35ef0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
35f00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
35f10 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
35f20 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74   function.** wit
35f30 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
35f40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e  connection] iden
35f50 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  tified by the fi
35f60 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
35f70 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
35f80 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
35f90 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
35fa0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
35fb0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
35fc0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
35fd0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
35fe0 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68  nction.** for th
35ff0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
36000 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
36010 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
36020 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
36030 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
36040 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
36050 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
36060 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64   a.** row is upd
36070 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
36080 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54  r deleted..** ^T
36090 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
360a0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
360b0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
360c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
360d0 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
360e0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
360f0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61  * ^The second ca
36100 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
36110 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
36120 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
36130 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f  TE_DELETE],.** o
36140 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
36150 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ], depending on 
36160 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
36170 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
36180 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20  llback.** to be 
36190 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
361a0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
361b0 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
361c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
361d0 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ain pointers to 
361e0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
361f0 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  and table name c
36200 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
36210 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e  fected row..** ^
36220 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
36230 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
36240 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
36250 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74  he row..** ^In t
36260 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
36270 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
36280 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20  e [rowid] after 
36290 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
362a0 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28   place..**.** ^(
362b0 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
362c0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
362d0 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
362e0 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
362f0 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
36300 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
36310 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
36320 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ce).)^.**.** ^In
36330 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
36340 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65  lementation, the
36350 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
36360 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
36370 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20  hen duplication 
36380 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
36390 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a   because of an.*
363a0 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c  * [ON CONFLICT |
363b0 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50   ON CONFLICT REP
363c0 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e  LACE] clause.  ^
363d0 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74  Nor is the updat
363e0 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65  e hook.** invoke
363f0 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20  d when rows are 
36400 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68  deleted using th
36410 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  e [truncate opti
36420 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  mization]..** Th
36430 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66  e exceptions def
36440 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72  ined in this par
36450 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61  agraph might cha
36460 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
36470 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
36480 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
36490 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c  update hook impl
364a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
364b0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
364c0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
364d0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
364e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
364f0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64   invoked the upd
36500 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61  ate hook.  Any a
36510 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
36520 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
36530 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
36540 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
36550 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
36560 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
36570 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
36580 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
36590 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74  ggered the updat
365a0 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  e hook..** Note 
365b0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
365c0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
365d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
365e0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
365f0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
36600 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
36610 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
36620 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
36630 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
36640 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64  ^The sqlite3_upd
36650 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ate_hook(D,C,P) 
36660 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75  function.** retu
36670 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65  rns the P argume
36680 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
36690 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20  ious call.** on 
366a0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
366b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
366c0 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
366d0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
366e0 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  on D..**.** See 
366f0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
36700 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d  3_commit_hook()]
36710 2c 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  , [sqlite3_rollb
36720 61 63 6b 5f 68 6f 6f 6b 28 29 5d 2c 0a 2a 2a 20  ack_hook()],.** 
36730 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
36740 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69  update_hook()] i
36750 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f  nterfaces..*/.vo
36760 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
36770 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
36780 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
36790 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
367a0 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
367b0 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
367c0 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
367d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
367e0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
367f0 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
36800 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f 52   Cache.** KEYWOR
36810 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68  DS: {shared cach
36820 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e}.**.** ^(This 
36830 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
36840 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
36850 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64  sharing of the d
36860 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a  atabase cache.**
36870 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61   and schema data
36880 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77   structures betw
36890 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  een [database co
368a0 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65  nnection | conne
368b0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68  ctions].** to th
368c0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e  e same database.
368d0 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   Sharing is enab
368e0 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
368f0 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61  ent is true.** a
36900 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74  nd disabled if t
36910 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66  he argument is f
36920 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43  alse.)^.**.** ^C
36930 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20  ache sharing is 
36940 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61  enabled and disa
36950 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69  bled for an enti
36960 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54  re process..** T
36970 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20  his is a change 
36980 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  as of SQLite ver
36990 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70  sion 3.5.0. In p
369a0 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  rior versions of
369b0 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72   SQLite,.** shar
369c0 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20  ing was enabled 
369d0 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  or disabled for 
369e0 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61  each thread sepa
369f0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  rately..**.** ^(
36a00 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e  The cache sharin
36a10 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68  g mode set by th
36a20 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66  is interface eff
36a30 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75  ects all subsequ
36a40 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
36a50 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
36a60 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
36a70 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  v2()], and [sqli
36a80 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
36a90 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62  * Existing datab
36aa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
36ab0 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65  continue use the
36ac0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a   sharing mode.**
36ad0 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66   that was in eff
36ae0 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20  ect at the time 
36af0 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64  they were opened
36b00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  .)^.**.** ^(This
36b10 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
36b20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
36b30 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73  shared cache was
36b40 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
36b50 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66  bled.** successf
36b60 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72  ully.  An [error
36b70 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
36b80 65 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a  ed otherwise.)^.
36b90 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 61  **.** ^Shared ca
36ba0 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
36bb0 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20  by default. But 
36bc0 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67  this might chang
36bd0 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72  e in.** future r
36be0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
36bf0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
36c00 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74   that care about
36c10 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
36c20 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20   setting should 
36c30 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c  set it explicitl
36c40 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73  y..**.** See Als
36c50 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72  o:  [SQLite Shar
36c60 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a  ed-Cache Mode].*
36c70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
36c80 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
36c90 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
36ca0 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74  API3REF: Attempt
36cb0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
36cc0 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  mory.**.** ^The 
36cd0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
36ce0 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61  memory() interfa
36cf0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
36d00 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f  ree N bytes.** o
36d10 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
36d20 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
36d30 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
36d40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a  ry allocations.*
36d50 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  * held by the da
36d60 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20  tabase library. 
36d70 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f    Memory used to
36d80 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a   cache database.
36d90 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72  ** pages to impr
36da0 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
36db0 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
36dc0 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
36dd0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74  emory..** ^sqlit
36de0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
36df0 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  y() returns the 
36e00 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
36e10 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a  actually freed,.
36e20 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  ** which might b
36e30 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74  e more or less t
36e40 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72  han the amount r
36e50 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68  equested..** ^Th
36e60 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
36e70 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69  e_memory() routi
36e80 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65  ne is a no-op re
36e90 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20  turning zero.** 
36ea0 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74  if SQLite is not
36eb0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
36ec0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
36ed0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
36ee0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
36ef0 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  : [sqlite3_db_re
36f00 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a  lease_memory()].
36f10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
36f20 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
36f30 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
36f40 52 45 46 3a 20 46 72 65 65 20 4d 65 6d 6f 72 79  REF: Free Memory
36f50 20 55 73 65 64 20 42 79 20 41 20 44 61 74 61 62   Used By A Datab
36f60 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
36f70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36f80 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  3_db_release_mem
36f90 6f 72 79 28 44 29 20 69 6e 74 65 72 66 61 63 65  ory(D) interface
36fa0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65   attempts to fre
36fb0 65 20 61 73 20 6d 75 63 68 20 68 65 61 70 0a 2a  e as much heap.*
36fc0 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70 6f 73 73  * memory as poss
36fd0 69 62 6c 65 20 66 72 6f 6d 20 64 61 74 61 62 61  ible from databa
36fe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
36ff0 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 5b   Unlike the.** [
37000 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
37010 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74 65 72 66  memory()] interf
37020 61 63 65 2c 20 74 68 69 73 20 69 6e 74 65 72 66  ace, this interf
37030 61 63 65 20 69 73 20 65 66 66 65 63 74 20 65 76  ace is effect ev
37040 65 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 6e 20  en.** when then 
37050 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
37060 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
37070 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
37080 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 6d 69 74  ption is.** omit
37090 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ted..**.** See a
370a0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65  lso: [sqlite3_re
370b0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a  lease_memory()].
370c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
370d0 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  b_release_memory
370e0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
370f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70  ** CAPI3REF: Imp
37100 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48  ose A Limit On H
37110 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e  eap Size.**.** ^
37120 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  The sqlite3_soft
37130 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
37140 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 61  interface sets a
37150 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20 74 68  nd/or queries th
37160 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20  e.** soft limit 
37170 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  on the amount of
37180 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61   heap memory tha
37190 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74  t may be allocat
371a0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  ed by SQLite..**
371b0 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76 65 73   ^SQLite strives
371c0 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20 6d 65   to keep heap me
371d0 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e  mory utilization
371e0 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20   below the soft 
371f0 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79  heap.** limit by
37200 20 72 65 64 75 63 69 6e 67 20 74 68 65 20 6e 75   reducing the nu
37210 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 68 65  mber of pages he
37220 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65 20 63  ld in the page c
37230 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 20  ache.** as heap 
37240 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20 61 70  memory usages ap
37250 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c 69 6d  proaches the lim
37260 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74  it..** ^The soft
37270 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 22   heap limit is "
37280 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 65 76  soft" because ev
37290 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 74 65  en though SQLite
372a0 20 73 74 72 69 76 65 73 20 74 6f 20 73 74 61 79   strives to stay
372b0 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c 69  .** below the li
372c0 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 63  mit, it will exc
372d0 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20 72 61  eed the limit ra
372e0 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65 72 61  ther than genera
372f0 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45  te.** an [SQLITE
37300 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20  _NOMEM] error.  
37310 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
37320 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
37330 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 73  mit .** is advis
37340 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ory only..**.** 
37350 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  ^The return valu
37360 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73  e from sqlite3_s
37370 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
37380 28 29 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  () is the size o
37390 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65  f.** the soft he
373a0 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 20 74  ap limit prior t
373b0 6f 20 74 68 65 20 63 61 6c 6c 2c 20 6f 72 20 6e  o the call, or n
373c0 65 67 61 74 69 76 65 20 69 6e 20 74 68 65 20 63  egative in the c
373d0 61 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 65 72 72  ase of an.** err
373e0 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 72 67  or.  ^If the arg
373f0 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 74  ument N is negat
37400 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63  ive.** then no c
37410 68 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74 6f  hange is made to
37420 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37430 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 68  imit.  Hence, th
37440 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a  e current.** siz
37450 65 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68 65  e of the soft he
37460 61 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 20  ap limit can be 
37470 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69 6e  determined by in
37480 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
37490 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
374a0 74 36 34 28 29 20 77 69 74 68 20 61 20 6e 65 67  t64() with a neg
374b0 61 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a  ative argument..
374c0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72  **.** ^If the ar
374d0 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f  gument N is zero
374e0 20 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20 68   then the soft h
374f0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69 73  eap limit is dis
37500 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  abled..**.** ^(T
37510 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
37520 69 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63  it is not enforc
37530 65 64 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  ed in the curren
37540 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
37550 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f  .** if one or mo
37560 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20  re of following 
37570 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 74  conditions are t
37580 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  rue:.**.** <ul>.
37590 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74  ** <li> The soft
375a0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 73   heap limit is s
375b0 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c  et to zero..** <
375c0 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75  li> Memory accou
375d0 6e 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  nting is disable
375e0 64 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e  d using a combin
375f0 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
37600 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
37610 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
37620 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c  NFIG_MEMSTATUS],
37630 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 20  ...) start-time 
37640 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  option and.**   
37650 20 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44     the [SQLITE_D
37660 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
37670 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
37680 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41  ption..** <li> A
37690 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61  n alternative pa
376a0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
376b0 6e 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63 69  ntation is speci
376c0 66 69 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  fied using.**   
376d0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66     [sqlite3_conf
376e0 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
376f0 49 47 5f 50 43 41 43 48 45 32 5d 2c 2e 2e 2e 29  IG_PCACHE2],...)
37700 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61  ..** <li> The pa
37710 67 65 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74  ge cache allocat
37720 65 73 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20  es from its own 
37730 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70  memory pool supp
37740 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 20  lied.**      by 
37750 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
37760 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
37770 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20  PAGECACHE],...) 
37780 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20  rather than.**  
37790 20 20 20 20 66 72 6f 6d 20 74 68 65 20 68 65 61      from the hea
377a0 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  p..** </ul>)^.**
377b0 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 69  .** Beginning wi
377c0 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  th SQLite versio
377d0 6e 20 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66  n 3.7.3, the sof
377e0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
377f0 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61  enforced.** rega
37800 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
37810 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
37820 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
37830 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a  RY_MANAGEMENT].*
37840 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
37850 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ption is invoked
37860 2e 20 20 57 69 74 68 20 5b 53 51 4c 49 54 45 5f  .  With [SQLITE_
37870 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
37880 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68  NAGEMENT],.** th
37890 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
378a0 74 20 69 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e  t is enforced on
378b0 20 65 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   every memory al
378c0 6c 6f 63 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f  location.  Witho
378d0 75 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  ut.** [SQLITE_EN
378e0 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
378f0 47 45 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66  GEMENT], the sof
37900 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
37910 6f 6e 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a  only enforced.**
37920 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
37930 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65  allocated by the
37940 20 70 61 67 65 20 63 61 63 68 65 2e 20 20 54 65   page cache.  Te
37950 73 74 69 6e 67 20 73 75 67 67 65 73 74 73 20 74  sting suggests t
37960 68 61 74 20 62 65 63 61 75 73 65 0a 2a 2a 20 74  hat because.** t
37970 68 65 20 70 61 67 65 20 63 61 63 68 65 20 69 73  he page cache is
37980 20 74 68 65 20 70 72 65 64 6f 6d 69 6e 61 74 65   the predominate
37990 20 6d 65 6d 6f 72 79 20 75 73 65 72 20 69 6e 20   memory user in 
379a0 53 51 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20  SQLite, most.** 
379b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c  applications wil
379c0 6c 20 61 63 68 69 65 76 65 20 61 64 65 71 75 61  l achieve adequa
379d0 74 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  te soft heap lim
379e0 69 74 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77  it enforcement w
379f0 69 74 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73  ithout.** the us
37a00 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e of [SQLITE_ENA
37a10 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
37a20 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  EMENT]..**.** Th
37a30 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
37a40 75 6e 64 65 72 20 77 68 69 63 68 20 53 51 4c 69  under which SQLi
37a50 74 65 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20  te will enforce 
37a60 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
37a70 6d 69 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67  mit may.** chang
37a80 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  es in future rel
37a90 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
37aa0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
37ab0 34 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  4 sqlite3_soft_h
37ac0 65 61 70 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69  eap_limit64(sqli
37ad0 74 65 33 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f  te3_int64 N);../
37ae0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
37af0 65 70 72 65 63 61 74 65 64 20 53 6f 66 74 20 48  eprecated Soft H
37b00 65 61 70 20 4c 69 6d 69 74 20 49 6e 74 65 72 66  eap Limit Interf
37b10 61 63 65 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ace.** DEPRECATE
37b20 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  D.**.** This is 
37b30 61 20 64 65 70 72 65 63 61 74 65 64 20 76 65 72  a deprecated ver
37b40 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  sion of the [sql
37b50 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
37b60 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74  imit64()].** int
37b70 65 72 66 61 63 65 2e 20 20 54 68 69 73 20 72 6f  erface.  This ro
37b80 75 74 69 6e 65 20 69 73 20 70 72 6f 76 69 64 65  utine is provide
37b90 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
37ba0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
37bb0 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77  * only.  All new
37bc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
37bd0 6f 75 6c 64 20 75 73 65 20 74 68 65 0a 2a 2a 20  ould use the.** 
37be0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
37bf0 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e  ap_limit64()] in
37c00 74 65 72 66 61 63 65 20 72 61 74 68 65 72 20 74  terface rather t
37c10 68 61 6e 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f  han this one..*/
37c20 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
37c30 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
37c40 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
37c50 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int N);.../*.** 
37c60 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63  CAPI3REF: Extrac
37c70 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74  t Metadata About
37c80 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54   A Column Of A T
37c90 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  able.**.** ^This
37ca0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
37cb0 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20   metadata about 
37cc0 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d  a specific colum
37cd0 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a  n of a specific.
37ce0 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c  ** database tabl
37cf0 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69  e accessible usi
37d00 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ng the [database
37d10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
37d20 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  dle.** passed as
37d30 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74   the first funct
37d40 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
37d50 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20  .** ^The column 
37d60 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
37d70 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69   the second, thi
37d80 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
37d90 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74  rameters to.** t
37da0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54  his function. ^T
37db0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
37dc0 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68  ter is either th
37dd0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
37de0 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20  tabase.** (i.e. 
37df0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20  "main", "temp", 
37e00 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64  or an attached d
37e10 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e  atabase) contain
37e20 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
37e30 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55  d.** table or NU
37e40 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55  LL. ^If it is NU
37e50 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74  LL, then all att
37e60 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20  ached databases 
37e70 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20  are searched.** 
37e80 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73  for the table us
37e90 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
37ea0 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74  orithm used by t
37eb0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
37ec0 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65  ne to.** resolve
37ed0 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62   unqualified tab
37ee0 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a  le references..*
37ef0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
37f00 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
37f10 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
37f20 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74  nction are the t
37f30 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a  able and column.
37f40 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ** name of the d
37f50 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72  esired column, r
37f60 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69  espectively. Nei
37f70 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61  ther of these pa
37f80 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20  rameters.** may 
37f90 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
37fa0 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75  Metadata is retu
37fb0 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20  rned by writing 
37fc0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f  to the memory lo
37fd0 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61  cations passed a
37fe0 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64  s the 5th.** and
37ff0 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61   subsequent para
38000 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
38010 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66  unction. ^Any of
38020 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73   these arguments
38030 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c   may be.** NULL,
38040 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
38050 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
38060 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61   element of meta
38070 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e  data is omitted.
38080 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71  .**.** ^(<blockq
38090 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
380a0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
380b0 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65  tr><th> Paramete
380c0 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72  r <th> Output<br
380d0 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63  >Type <th>  Desc
380e0 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  ription.**.** <t
380f0 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20  r><td> 5th <td> 
38100 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
38110 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74   Data type.** <t
38120 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20  r><td> 6th <td> 
38130 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
38140 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74   Name of default
38150 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
38160 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nce.** <tr><td> 
38170 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  7th <td> int    
38180 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
38190 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  f column has a N
381a0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
381b0 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38  nt.** <tr><td> 8
381c0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
381d0 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
381e0 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
381f0 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
38200 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39  EY.** <tr><td> 9
38210 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
38220 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
38230 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f   column is [AUTO
38240 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f  INCREMENT].** </
38250 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
38260 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
38270 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  ^The memory poin
38280 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68  ted to by the ch
38290 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73  aracter pointers
382a0 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68   returned for th
382b0 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e  e.** declaration
382c0 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74   type and collat
382d0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
382e0 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c  valid only until
382f0 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c   the next.** cal
38300 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20  l to any SQLite 
38310 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  API function..**
38320 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
38330 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61  ified table is a
38340 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20  ctually a view, 
38350 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
38360 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
38370 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
38380 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22  fied column is "
38390 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72  rowid", "oid" or
383a0 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61   "_rowid_" and a
383b0 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52  n.** [INTEGER PR
383c0 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d  IMARY KEY] colum
383d0 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
383e0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
383f0 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a  then the output.
38400 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
38410 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78  e set for the ex
38420 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
38430 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74  d column. ^(If t
38440 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78  here is no.** ex
38450 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
38460 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  d [INTEGER PRIMA
38470 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20  RY KEY] column, 
38480 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a  then the output.
38490 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
384a0 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73  e set as follows
384b0 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
384c0 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20       data type: 
384d0 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20  "INTEGER".**    
384e0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
384f0 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a  nce: "BINARY".**
38500 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30       not null: 0
38510 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20  .**     primary 
38520 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75  key: 1.**     au
38530 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a  to increment: 0.
38540 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a  ** </pre>)^.**.*
38550 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f  * ^(This functio
38560 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f  n may load one o
38570 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66  r more schemas f
38580 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c  rom database fil
38590 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72  es. If an.** err
385a0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
385b0 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f   this process, o
385c0 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74  r if the request
385d0 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  ed table or colu
385e0 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  mn.** cannot be 
385f0 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72  found, an [error
38600 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
38610 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  ed and an error 
38620 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20  message left.** 
38630 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
38640 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f   connection] (to
38650 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73   be retrieved us
38660 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  ing sqlite3_errm
38670 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  sg()).)^.**.** ^
38680 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79  This API is only
38690 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
386a0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
386b0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
386c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
386d0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
386e0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
386f0 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
38700 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
38710 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65  _table_column_me
38720 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65  tadata(.  sqlite
38730 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
38740 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74        /* Connect
38750 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ion handle */.  
38760 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
38770 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44  ame,        /* D
38780 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20  atabase name or 
38790 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  NULL */.  const 
387a0 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65  char *zTableName
387b0 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e  ,     /* Table n
387c0 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ame */.  const c
387d0 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65  har *zColumnName
387e0 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e  ,    /* Column n
387f0 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ame */.  char co
38800 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65  nst **pzDataType
38810 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20  ,    /* OUTPUT: 
38820 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79  Declared data ty
38830 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  pe */.  char con
38840 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20  st **pzCollSeq, 
38850 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43      /* OUTPUT: C
38860 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
38870 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20  e name */.  int 
38