/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 116dc731361549ee3fc79dcebace11b57d24dcfd:


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 65 64 20  y are supported 
07d0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
07e0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
07f0: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
0800: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
0810: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
0820: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
0830: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
0840: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
0850: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
0860: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
0870: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
0880: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
0890: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
08a0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
08b0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
08c0: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
08d0: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
08e0: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
08f0: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
0900: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
0910: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
0920: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
0930: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
0940: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
0950: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
0960: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
0970: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
0980: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0990: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
09a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
09b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
09c0: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
09d0: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
09e0: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
09f0: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
0a00: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
0a10: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
0a20: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0a30: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
0a40: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0a50: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
0a60: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a70: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
0a80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0a90: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
0aa0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0ab0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
0ac0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ad0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0ae0: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
0af0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
0b00: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
0b10: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0b20: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0b30: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
0b40: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
0b50: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
0b60: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0b70: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
0b80: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
0b90: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
0ba0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0bb0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
0bc0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0bd0: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
0be0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bf0: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
0c00: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
0c10: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
0c20: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
0c30: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0c40: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0c50: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
0c60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
0c70: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
0c80: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
0c90: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0ca0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
0cb0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
0cc0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
0cd0: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
0ce0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
0cf0: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
0d00: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
0d10: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
0d20: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
0d30: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
0d40: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
0d50: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
0d60: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
0d70: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
0d80: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
0d90: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
0da0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
0db0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
0dc0: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
0dd0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
0de0: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
0df0: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
0e00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0e10: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
0e20: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
0e30: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
0e40: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
0e50: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
0e60: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
0e70: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
0e80: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
0e90: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
0ea0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
0eb0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
0ec0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
0ed0: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
0ee0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
0ef0: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
0f00: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
0f10: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
0f20: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
0f30: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
0f40: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0f50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0f60: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
0f70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0f80: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
0f90: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
0fa0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
0fb0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
0fc0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
0fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
0fe0: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
0ff0: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69  "--VERS--".#defi
1000: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1010: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49  N_NUMBER --VERSI
1020: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66  ON-NUMBER--.#def
1030: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1040: 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55  E_ID      "--SOU
1050: 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a  RCE-ID--"../*.**
1060: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1070: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
1080: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
1090: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10a0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
10b0: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
10c0: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
10d0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
10e0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
10f0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1100: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1110: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1120: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1130: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1140: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
1150: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
1160: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1170: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
1180: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
1190: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11a0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
11b0: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
11c0: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
11d0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
11e0: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
11f0: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1200: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1210: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1220: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1230: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1240: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
1250: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
1260: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
1270: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
1280: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
1290: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12b0: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
12c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
12d0: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
12e0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
12f0: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1300: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1310: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1320: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1330: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1340: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
1350: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
1360: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1370: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1380: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1390: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13a0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
13b0: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
13c0: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
13d0: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
13e0: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
13f0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1400: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1410: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1420: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1430: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1440: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
1450: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1460: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
1470: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
1480: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1490: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14a0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
14b0: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
14c0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
14d0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
14e0: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
14f0: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1510: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1520: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1530: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1540: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
1550: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
1560: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
1570: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
1580: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
1590: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15a0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
15b0: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
15c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
15d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
15e0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
15f0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1600: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1610: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1620: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ()]..*/.SQLITE_E
1630: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
1640: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1650: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
1660: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1670: 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20  on(void);.const 
1680: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1690: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e  urceid(void);.in
16a0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
16b0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
16c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16d0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
16e0: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
16f0: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1700: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1710: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1720: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1730: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1740: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1750: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1760: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
1770: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
1780: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1790: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
17a0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
17b0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
17c0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
17d0: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
17e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
17f0: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1800: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1810: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1820: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1830: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1840: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1850: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1860: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
1870: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
1880: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
18a0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
18b0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
18c0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
18d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
18e0: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
18f0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1900: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1910: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1920: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1930: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1940: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1950: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1960: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1970: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1980: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
19a0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
19b0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19c0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
19d0: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
19e0: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
19f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1a00: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1a10: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1a20: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1a30: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1a40: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1a50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a60: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1a80: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1a90: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1aa0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1ab0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1ac0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1ad0: 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65  DIAGS.int sqlite
1ae0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1af0: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20  used(const char 
1b00: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73  *zOptName);.cons
1b10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1b20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1b40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1b60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1b70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1b80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1b90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1ba0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1bb0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1bc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1bd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1be0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1bf0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1c00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1c10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1c20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1c30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1c40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1c50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1c60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1c70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1c80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1c90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ca0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1cb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1cc0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1cd0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ce0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1cf0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1d10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1d20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1d30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1d40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1d50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1d60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1d70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1d80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1d90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1da0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1db0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1dc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1dd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1de0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1df0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1e00: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1e10: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1e20: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1e30: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1e40: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1e50: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
1e60: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
1e70: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
1e80: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
1e90: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1ea0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
1eb0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
1ec0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1ed0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
1ee0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
1ef0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
1f00: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
1f10: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
1f20: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
1f30: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f40: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
1f50: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
1f60: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
1f70: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
1f80: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
1f90: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1fa0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
1fb0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1fc0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
1fd0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fe0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
1ff0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2000: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2010: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2020: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2030: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2040: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2050: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2060: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2080: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
20a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
20b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
20c0: 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65  IALIZED].  ^(The
20d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
20e0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
20f0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
2100: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
2110: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2120: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
2130: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
2140: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
2150: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
2160: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
2170: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
2180: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
2190: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
21a0: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
21b0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
21c0: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
21d0: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
21e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
21f0: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
2200: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
2210: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2220: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2230: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  rmation..*/.int 
2240: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2250: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
2260: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
2270: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
2280: 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  andle.** KEYWORD
2290: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
22a0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
22b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
22c0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
22d0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
22e0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
22f0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
2300: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
2310: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
2320: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
2330: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
2340: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
2350: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
2360: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
2370: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
2380: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2390: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
23a0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
23b0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
23c0: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
23d0: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
23e0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
23f0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2400: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72  3_close_v2()] ar
2410: 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  e its destructor
2420: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  s.  There are ma
2430: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65  ny other.** inte
2440: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
2450: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2460: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2470: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2480: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
2490: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
24a0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
24b0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
24c0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
24d0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
24e0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
24f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
2500: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
2510: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
2520: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a  Integer Types.**
2530: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
2540: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
2550: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
2560: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
2570: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
2580: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
2590: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
25a0: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
25b0: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
25c0: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
25d0: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
25e0: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
25f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
2600: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
2610: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
2620: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69  rred type defini
2630: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71  tions..** The sq
2640: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
2650: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2660: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  es are supported
2670: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
2680: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
2690: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
26a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
26b0: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  nd sqlite_int64 
26c0: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
26d0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a  integer values.*
26e0: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33  * between -92233
26f0: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61  72036854775808 a
2700: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35  nd +922337203685
2710: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76  4775807 inclusiv
2720: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2730: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73  te3_uint64 and s
2740: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2750: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2760: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20  eger values .** 
2770: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31  between 0 and +1
2780: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31  8446744073709551
2790: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a  615 inclusive..*
27a0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
27b0: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
27c0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
27d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
27e0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
27f0: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
2800: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2810: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
2820: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2830: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2840: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2850: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2860: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2870: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2880: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2890: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
28a0: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
28b0: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
28c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
28d0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
28e0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28f0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2900: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2910: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2920: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2930: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2940: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2950: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2960: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2970: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2980: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2990: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
29a0: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
29b0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
29c0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
29d0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
29e0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
29f0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2a00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2a10: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2a20: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
2a30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2a40: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2a50: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2a60: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2a70: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2a80: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2a90: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2aa0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ab0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2ac0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2ad0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2ae0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2af0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2b00: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2b10: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2b20: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2b30: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2b40: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2b50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b60: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2b70: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2b80: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2b90: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ba0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2bb0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2bc0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2bd0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2c00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2c10: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2c20: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2c30: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2c40: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2c50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2c60: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2c70: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2c80: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2c90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ca0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2cb0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2cc0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2cd0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ce0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2cf0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2d00: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2d10: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2d20: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2d30: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2d40: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2d50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2d60: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2d70: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2d80: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2d90: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2da0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2db0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2dc0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2dd0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2de0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2df0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2e00: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
2e10: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e20: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2e30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e40: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
2e50: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
2e60: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
2e70: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
2e80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
2e90: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
2ea0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
2eb0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
2ec0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
2ed0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
2ee0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
2ef0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
2f00: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
2f10: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
2f20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
2f30: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f50: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2f60: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
2f70: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f80: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
2f90: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
2fa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
2fb0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
2fc0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
2fd0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
2fe0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
2ff0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3000: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3010: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3020: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3030: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3040: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3050: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3060: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3070: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3080: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3090: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
30a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
30b0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
30c0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
30d0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
30e0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
30f0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3100: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3110: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3120: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3130: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3140: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3150: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3160: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3170: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
31a0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
31b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
31c0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
31d0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
31e0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
31f0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3200: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3210: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3220: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3230: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3240: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3250: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3260: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3270: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3280: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3290: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
32a0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
32b0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
32c0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
32d0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
32e0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
32f0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3300: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3310: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3320: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3330: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3340: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3350: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3360: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3370: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3380: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
3390: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
33a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
33b0: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
33c0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
33d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
33f0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
3400: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
3410: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3420: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3430: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3440: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3450: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3460: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3470: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3480: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3490: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
34a0: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
34b0: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
34c0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
34d0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
34e0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
34f0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
3500: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
3510: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3520: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3530: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3540: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3550: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3580: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3590: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
35a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
35b0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
35c0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
35d0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
35e0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
35f0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
3600: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3610: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3620: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3630: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3640: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3650: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3660: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3670: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3680: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3690: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
36a0: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
36b0: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
36c0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
36d0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
36e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
36f0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3700: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3710: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3720: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3730: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3740: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3750: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3760: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3770: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3780: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3790: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
37a0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
37b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
37c0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
37d0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
37e0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
37f0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3800: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3810: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3820: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3830: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3840: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3850: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3860: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3870: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3880: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3890: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
38a0: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
38b0: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
38c0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
38d0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
38e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
38f0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3900: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3910: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3920: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3930: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3950: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3960: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3970: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3980: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3990: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
39a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
39b0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
39c0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
39d0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
39e0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
39f0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3a00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3a10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3a20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3a30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3a40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3a50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3a60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3a70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3a80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3a90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3aa0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3ab0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3ac0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3ad0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ae0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3af0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3b00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3b20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3b30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3b40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3b50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3b60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3b70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3b80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3b90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ba0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3bb0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3bc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3bd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3be0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3c10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3c20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3c30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3c40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3c50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3c60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3c70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3c80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3c90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ca0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3cb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3cc0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3cd0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ce0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3cf0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3d00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3d10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3d20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3d30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3d40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3d50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3d60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3d70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3d80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3d90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3da0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3db0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3dc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3dd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3de0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3df0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
3e00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e10: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
3e20: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3e30: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3e40: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
3e50: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3e70: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3e80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e90: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
3ea0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3eb0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3ec0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3ed0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3ef0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3f00: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3f10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3f20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3f30: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3f40: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3f50: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3f60: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3f70: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3f80: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3f90: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3fa0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3fb0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
3fc0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
3fd0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ff0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4000: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4010: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4040: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4050: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4060: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4070: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4080: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4090: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
40d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
40e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
40f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4110: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4120: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4130: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4140: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4150: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4160: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4170: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4180: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4190: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
41e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
41f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4200: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4210: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4220: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4230: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4240: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4250: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4260: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4270: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4280: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4290: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
42a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
42b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
42c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
42d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
42e0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
42f0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
4300: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4310: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4320: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4330: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4340: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4350: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4360: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4370: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4380: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4390: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
43a0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
43b0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
43c0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
43f0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4400: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4420: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4430: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4440: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4450: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4460: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4470: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4480: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
44b0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
44c0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
44d0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
44e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
44f0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4500: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4510: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4520: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4540: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4550: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4560: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4570: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4580: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4590: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
45a0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
45b0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
45e0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
45f0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4600: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4610: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4620: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4630: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4640: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4650: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4660: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4670: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4680: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4690: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
46a0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
46b0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
46c0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
46d0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
46e0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
46f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4700: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4710: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4720: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4730: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4740: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4750: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4760: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4770: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4780: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4790: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
47a0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
47b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47c0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
47d0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
47e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
47f0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4800: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4810: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4820: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4830: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4840: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4850: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4860: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4880: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4890: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
48a0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
48b0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
48c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
48d0: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
48e0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
48f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4900: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4910: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4920: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4930: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4950: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4960: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4970: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4980: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
49a0: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
49b0: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
49c0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
49d0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
49e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49f0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4a00: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4a10: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4a20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4a30: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4a40: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4a50: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4a60: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4a70: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4a80: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4a90: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4aa0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4ab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ac0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ad0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4ae0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4af0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4b00: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4b10: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4b20: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4b30: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4b40: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b50: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b60: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4b70: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4b80: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4b90: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4ba0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4bb0: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4bc0: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4bd0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4be0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4bf0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4c00: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4c10: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4c20: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4c30: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4c40: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4c50: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4c60: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4c70: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4c80: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4c90: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4ca0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4cb0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4cc0: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4cd0: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4ce0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4cf0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4d00: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4d10: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4d20: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4d30: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4d40: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65  ese [extended re
4d50: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
4d60: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4d70: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4d80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4d90: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4da0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4db0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4dc0: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f  codes()] API.  O
4dd0: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20  r, the extended 
4de0: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
4df0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
4e00: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  r can be obtaine
4e10: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
4e20: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
4e30: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  code()]..*/.#def
4e40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e50: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
4e60: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e70: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
4e80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4e90: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
4ea0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4eb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
4ec0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
4ed0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
4ee0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4ef0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
4f00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
4f10: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
4f20: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f30: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
4f50: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
4f60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f70: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
4f90: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
4fa0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
4fb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
4fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fe0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
4ff0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5000: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
5010: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5020: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
5030: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5040: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
5050: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5060: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5070: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5080: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5090: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
50b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
50d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
50f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5100: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
5110: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5120: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
5130: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5140: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
5150: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5160: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5170: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5180: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5190: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
51a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
51b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51c0: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
51d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
51f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5200: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
5210: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5220: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
5230: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5240: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
5250: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
5260: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
5270: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5280: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
5290: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
52b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
52c0: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
52d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
52f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5300: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
5310: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5320: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
5330: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5340: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
5350: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5360: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
5390: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
53b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53c0: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
53d0: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
53e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
53f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5400: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
5410: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5420: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
5430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5440: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
5450: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5460: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
5470: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5480: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
5490: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
54a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
54b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54c0: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
54d0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
54e0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
54f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5500: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
5510: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5520: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
5530: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5540: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f  ITE_BUSY_SNAPSHO
5550: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  T           (SQL
5560: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32  ITE_BUSY   |  (2
5570: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5580: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5590: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
55a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
55b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
55c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
55d0: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
55e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
55f0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5600: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5610: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20  N_FULLPATH      
5620: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5630: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  N | (3<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5650: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  PEN_CONVPATH    
5660: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5670: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  PEN | (4<<8)).#d
5680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
5690: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
56a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
56b0: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
56c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
56d0: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
56e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
56f0: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
5720: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5730: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
5740: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5750: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42  E_READONLY_ROLLB
5760: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  ACK       (SQLIT
5770: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c  E_READONLY | (3<
5780: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5790: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d  ITE_READONLY_DBM
57a0: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c  OVED        (SQL
57b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57c0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
57d0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
57e0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
57f0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5800: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5810: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5820: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5830: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5840: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5850: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5860: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5870: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5880: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
58a0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
58b0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
58c0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
58d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58e0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
58f0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5900: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5910: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5920: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5930: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5940: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5950: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5960: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5970: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5980: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5990: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
59a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59b0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
59c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59d0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
59e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
59f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5a00: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5a20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a30: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a40: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a60: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5a70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a80: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
5a90: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5aa0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
5ab0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5ac0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
5ad0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
5ae0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
5af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5b00: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
5b10: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
5b20: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
5b30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
5b40: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
5b50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
5b60: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
5b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
5b80: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
5b90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
5ba0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  TH | (1<<8))../*
5bb0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
5bc0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
5bd0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
5be0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
5bf0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
5c00: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
5c10: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5c20: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5c30: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5c40: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5c50: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5c60: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5c70: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
5c80: 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  hod..*/.#define 
5c90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5ca0: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
5cb0: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66  0000001  /* Ok f
5cc0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5cd0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5cf0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
5d00: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66  0000002  /* Ok f
5d10: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d20: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
5d40: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
5d50: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66  0000004  /* Ok f
5d60: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d70: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
5d90: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
5da0: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20  0000008  /* VFS 
5db0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5dc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
5dd0: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
5de0: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20  0000010  /* VFS 
5df0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f  SQLITE_OPEN_AUTO
5e10: 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30  PROXY        0x0
5e20: 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20  0000020  /* VFS 
5e30: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
5e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5e60: 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66  0000040  /* Ok f
5e70: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5e80: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5e90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f  SQLITE_OPEN_MEMO
5ea0: 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30  RY           0x0
5eb0: 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66  0000080  /* Ok f
5ec0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5ed0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ee0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5ef0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f00: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20  0000100  /* VFS 
5f10: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5f30: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f40: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20  0000200  /* VFS 
5f50: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
5f70: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
5f80: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20  0000400  /* VFS 
5f90: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5fb0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
5fc0: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20  0000800  /* VFS 
5fd0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fe0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5ff0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
6000: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20  0001000  /* VFS 
6010: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6020: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
6030: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
6040: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20  0002000  /* VFS 
6050: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
6070: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
6080: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20  0004000  /* VFS 
6090: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
60a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
60b0: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
60c0: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0008000  /* Ok f
60d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
60e0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
60f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
6100: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
6110: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0010000  /* Ok f
6120: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6130: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6140: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
6150: 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30  EDCACHE      0x0
6160: 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0020000  /* Ok f
6170: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6180: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6190: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
61a0: 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30  ATECACHE     0x0
61b0: 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0040000  /* Ok f
61c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
61d0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
61e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20  SQLITE_OPEN_WAL 
61f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6200: 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20  0080000  /* VFS 
6210: 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65  only */../* Rese
6220: 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20  rved:           
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6240: 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a  00F00000 */../*.
6250: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
6260: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
6270: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
6280: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6290: 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  tics method of t
62a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
62b0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
62c0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
62d0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
62e0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a  vector of these.
62f0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
6300: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
6310: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
6320: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
6330: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
6340: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
6350: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
6360: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6370: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
63a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
63b0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
63c0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
63d0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
63e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
63f0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6400: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6410: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6420: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6430: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6440: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6450: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6460: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6470: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6480: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6490: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
64a0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
64b0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
64c0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
64d0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
64e0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
64f0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6500: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6510: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6520: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6530: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6550: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6560: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6570: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6580: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6590: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
65a0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
65b0: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
65c0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
65d0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
65e0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
65f0: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
6600: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
6610: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
6620: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
6630: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
6640: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
6650: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
6660: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
6670: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
6680: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
6690: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
66a0: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
66b0: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
66c0: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
66d0: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  be unchanged.  T
66e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66f0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6700: 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e  _OPEN.** flag in
6710: 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69  dicate that a fi
6720: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6730: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6740: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6750: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6760: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6770: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6780: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6790: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
67a0: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
67b0: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
67c0: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
67d0: 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65  ivileges..*/.#de
67e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
67f0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6800: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6810: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6830: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6840: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6850: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6860: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6870: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6880: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6890: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
68a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
68b0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
68c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
68d0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
68e0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
68f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6900: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6910: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6920: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6940: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6950: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6970: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6980: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6990: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
69a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69b0: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
69c0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
69d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
69f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6a00: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a10: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6a20: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6a30: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6a40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6a50: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6a60: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a80: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6a90: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6aa0: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6ac0: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
6ad0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a      0x00002000..
6ae0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6af0: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6b00: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
6b10: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
6b20: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6b30: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
6b40: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
6b50: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
6b60: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
6b70: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
6b80: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
6b90: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6ba0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
6bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6bc0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6be0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
6bf0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
6c00: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6c10: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6c20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6c30: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
6c40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6c50: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
6c60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c70: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
6c80: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
6c90: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
6ca0: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
6cb0: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
6cc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6cd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6ce0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6cf0: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6d00: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6d10: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
6d20: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
6d30: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
6d40: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
6d50: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
6d60: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
6d70: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
6d80: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
6d90: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
6da0: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
6db0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
6dc0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
6dd0: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
6de0: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
6df0: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
6e00: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e10: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
6e20: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6e30: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
6e40: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6e50: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
6e60: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6e70: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
6e80: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
6e90: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
6ea0: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
6eb0: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
6ec0: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
6ed0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6ee0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6ef0: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
6f00: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
6f10: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
6f20: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
6f30: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
6f40: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
6f50: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
6f60: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
6f70: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
6f80: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
6f90: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
6fa0: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
6fb0: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
6fc0: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
6fd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6fe0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6ff0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
7000: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
7010: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
7020: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
7030: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
7040: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
7050: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
7060: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
7070: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
7080: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
7090: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
70a0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
70b0: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
70c0: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
70d0: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
70e0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
70f0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7100: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
7110: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
7120: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
7130: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
7140: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
7150: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
7160: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
7170: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
7180: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7190: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
71a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71b0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
71c0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
71d0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
71e0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
71f0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
7200: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7210: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
7220: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
7230: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7240: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
7250: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
7260: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
7270: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
7280: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
7290: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
72a0: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
72b0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
72c0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
72d0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
72e0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
72f0: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
7300: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
7310: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
7320: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
7330: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
7340: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7350: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
7360: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
7370: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
7380: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
7390: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
73a0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
73b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
73c0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
73d0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
73e0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
73f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7400: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
7410: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
7420: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
7430: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7440: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
7450: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
7460: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
7470: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
7480: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7490: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
74a0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
74b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
74c0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
74d0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
74e0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
74f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7500: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
7510: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
7520: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
7530: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
7540: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7550: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
7560: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
7570: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
7580: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
7590: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
75a0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
75b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
75c0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
75d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
75e0: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
75f0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7600: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7610: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
7620: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
7630: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
7640: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
7650: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
7660: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
7670: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7680: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
7690: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
76a0: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
76b0: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
76c0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
76d0: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
76e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
76f0: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
7700: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7710: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
7720: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7730: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
7740: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
7750: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
7760: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
7770: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
7780: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
7790: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
77a0: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
77b0: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
77c0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
77d0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
77e0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
77f0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7800: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
7810: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7820: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
7830: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
7840: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
7850: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
7860: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
7870: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
7880: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
7890: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
78a0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
78b0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
78c0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
78d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
78e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
78f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7900: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7910: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7920: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
7930: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7940: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
7950: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7960: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
7970: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
7980: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
7990: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
79a0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
79b0: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
79c0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
79d0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
79e0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
79f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
7a00: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
7a10: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
7a20: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
7a30: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
7a40: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
7a50: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
7a60: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
7a70: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
7a80: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
7a90: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
7aa0: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
7ab0: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
7ac0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7ad0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
7ae0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
7af0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
7b00: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
7b10: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
7b20: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
7b30: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
7b40: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7b50: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
7b60: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
7b70: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
7b80: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
7b90: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
7ba0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
7bb0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
7bc0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
7bd0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
7be0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
7bf0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
7c00: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
7c10: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
7c20: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
7c30: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
7c40: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
7c50: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
7c60: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
7c70: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
7c80: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
7c90: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
7ca0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
7cb0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
7cc0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
7cd0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
7ce0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
7cf0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
7d00: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
7d10: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
7d20: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
7d30: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
7d40: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
7d50: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
7d60: 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63  se..** A [file c
7d70: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c  ontrol opcodes |
7d80: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7d90: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7da0: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7db0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7dc0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7dd0: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7de0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7df0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7e00: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7e10: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7e20: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7e30: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7e40: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7e50: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7e60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7e70: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7e80: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7e90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7ea0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7eb0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7ec0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7ed0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7ee0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7ef0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7f00: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7f10: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7f20: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7f30: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7f40: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7f50: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7f60: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7f70: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7f80: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7f90: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7fa0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7fb0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7fc0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7fd0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7fe0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7ff0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
8000: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8010: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
8040: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8050: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
8060: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8070: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
8080: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8090: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
80a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80b0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
80c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
80d0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
80e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80f0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
8100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8110: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
8120: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8130: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8140: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8150: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8160: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8170: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8180: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8190: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
81a0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
81b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
81c0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
81d0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
81e0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
81f0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
8200: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
8210: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
8220: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
8230: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8240: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8250: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8260: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8270: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8280: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8290: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
82a0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
82b0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
82c0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
82d0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
82e0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
82f0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8300: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8310: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8320: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
8330: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8340: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8350: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8360: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8370: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8380: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8390: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
83a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
83b0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
83c0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
83d0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
83e0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
83f0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
8400: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
8410: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
8420: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
8430: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8440: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8450: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8460: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8470: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8480: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8490: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
84a0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
84b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
84c0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
84d0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
84e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84f0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8500: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
8510: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
8520: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
8530: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8540: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8550: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8560: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8570: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8580: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8590: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
85a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
85b0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
85c0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
85d0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
85e0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
85f0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
8600: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
8610: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
8620: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
8630: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8640: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8650: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8660: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8670: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8680: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8690: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
86a0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
86b0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
86c0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
86e0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
86f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8700: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8710: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8720: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8730: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8740: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8750: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8760: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8770: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8780: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8790: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
87a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
87b0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
87c0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
87d0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
87e0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
87f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8800: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8810: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8820: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8840: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8850: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8860: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8870: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8880: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8890: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
88a0: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
88d0: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
88e0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
88f0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
8900: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8910: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8920: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
8930: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8940: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8950: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8960: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8970: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8980: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8990: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
89a0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
89b0: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
89c0: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
89d0: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
89e0: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
89f0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
8a00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8a10: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8a20: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8a30: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8a40: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8a50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8a60: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8a70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8a80: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8a90: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8aa0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8ab0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8ac0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8ad0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8ae0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8af0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8b00: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8b10: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8b20: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8b30: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8b40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8b50: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8b60: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8b70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8b80: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8b90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8ba0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8bb0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8bc0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8bd0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8be0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8bf0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8c00: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8c10: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
8c20: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
8c30: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
8c40: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
8c50: 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a  fined..** <ul>.*
8c60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8c70: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8c80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8c90: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8ca0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8cb0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8cc0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8cd0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8ce0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8cf0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8d00: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8d10: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8d20: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8d30: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8d40: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8d50: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8d60: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8d70: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8d80: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8d90: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8da0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8db0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8dc0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8dd0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8de0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8df0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8e00: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8e10: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8e20: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8e30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8e40: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8e50: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8e60: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8e70: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8e80: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8e90: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8ea0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8eb0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8ec0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8ed0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8ee0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
8ef0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
8f00: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
8f10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
8f20: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
8f30: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
8f40: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8f50: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8f60: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
8f70: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8f80: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8f90: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8fa0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8fb0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8fc0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8fd0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8fe0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8ff0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9000: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9010: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9020: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9030: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9040: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
9050: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9060: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9070: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9080: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9090: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
90a0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
90b0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
90c0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
90d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
90e0: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
90f0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9100: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
9110: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
9120: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9130: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9140: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9150: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9170: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9180: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9190: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
91a0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
91b0: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
91c0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
91d0: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
91e0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
91f0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9200: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9210: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
9220: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
9230: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9240: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9250: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9260: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9270: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9280: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9290: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
92a0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
92b0: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
92c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
92d0: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
92e0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
92f0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9300: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
9310: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9320: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
9330: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9340: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
9350: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
9360: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9370: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9380: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9390: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
93a0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
93b0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
93c0: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
93d0: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
93e0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
93f0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9400: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
9410: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9420: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9430: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9440: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9460: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9470: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9480: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9490: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
94a0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
94b0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
94c0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
94d0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
94e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
94f0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9500: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9510: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9520: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
9530: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9540: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
9550: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
9560: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9570: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9580: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9590: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
95a0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
95b0: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
95c0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
95d0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
95e0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
95f0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9600: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
9610: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
9620: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
9630: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9640: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9650: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9660: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9670: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9680: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9690: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
96a0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
96b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
96c0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
96d0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
96e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
96f0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9700: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9710: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9720: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9730: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9740: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9750: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9760: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9770: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9780: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9790: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
97a0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
97b0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
97c0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
97d0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
97e0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
97f0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9800: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9810: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9820: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9830: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9840: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9850: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9860: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9870: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9880: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9890: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
98a0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
98b0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
98c0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
98d0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
98e0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
98f0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9900: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9910: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9920: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9930: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9940: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9950: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9960: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9970: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9980: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9990: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
99a0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
99b0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
99c0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
99d0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
99e0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
99f0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9a00: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9a10: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9a20: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9a30: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9a40: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9a50: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9a60: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9a70: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9a80: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9a90: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9aa0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9ab0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9ac0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9ad0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9ae0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9af0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9b00: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9b10: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9b20: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9b30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9b40: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9b50: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9b60: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9b70: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9b80: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9b90: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9ba0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9bb0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9bc0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9bd0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9be0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9bf0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9c00: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9c10: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9c20: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9c30: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9c40: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9c50: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9c60: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9c70: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9c80: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9c90: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9ca0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9cb0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9cc0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9cd0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9ce0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9cf0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9d00: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9d10: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9d20: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9d30: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9d40: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9d50: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9d60: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9d70: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9d80: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9d90: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9da0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9db0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9dc0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9dd0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9de0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9df0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9e00: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9e10: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9e20: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9e30: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9e40: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9e50: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9e60: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9e70: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9e80: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9e90: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9ea0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9eb0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9ec0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ed0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9ee0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9ef0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9f00: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9f10: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9f20: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9f30: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9f40: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9f50: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9f60: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9f70: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
9f80: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
9f90: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
9fa0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
9fb0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
9fc0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
9fd0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9fe0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9ff0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a000: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a010: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a020: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a030: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a040: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a050: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a060: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a070: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a080: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a090: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a0a0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a0b0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a0c0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a0d0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a0e0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a0f0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a100: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a110: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a120: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a130: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a140: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a150: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a160: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a170: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a180: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a190: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a1a0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a1b0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a1c0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a1d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a1e0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a1f0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a200: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a210: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a220: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a230: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a240: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a250: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a260: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a270: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a280: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a290: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a2a0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a2b0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a2c0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a2d0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a2e0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a2f0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a300: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a310: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a320: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a330: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a340: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a350: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a360: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a370: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a380: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a390: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a3a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a3b0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a3c0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a3d0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a3e0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a3f0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a400: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a410: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a420: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a430: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a440: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a450: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a460: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a470: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a480: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a490: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a4a0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a4b0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a4c0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a4d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a4e0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a4f0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a500: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a510: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a520: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a530: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a540: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a550: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a560: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a570: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a580: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a590: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a5a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a5b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a5c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a5d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a5e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a5f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a600: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a610: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a620: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a630: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a640: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a650: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a660: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a670: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a680: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a690: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a6a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a6b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a6c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a6d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a6e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a6f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a700: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a710: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a720: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a730: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a740: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a750: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a760: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a770: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a780: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a790: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a7a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a7b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a7c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a7d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a7e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a7f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a800: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a810: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a820: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a830: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a840: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a850: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a860: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a870: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a880: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a890: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a8a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a8b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a8c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a8d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a8e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a8f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a900: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a910: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a920: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a930: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a940: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a950: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a960: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a970: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a980: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a990: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a9a0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a9b0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a9c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a9d0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a9e0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a9f0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
aa00: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
aa10: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
aa20: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
aa30: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
aa40: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
aa50: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
aa60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa70: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
aa80: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
aa90: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
aaa0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
aab0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
aac0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
aad0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
aae0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
aaf0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
ab00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ab10: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
ab20: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
ab30: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
ab40: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
ab50: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
ab60: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
ab70: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
ab80: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
ab90: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
aba0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
abb0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
abc0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
abd0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
abe0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
abf0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
ac00: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
ac10: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
ac20: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
ac30: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
ac40: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
ac50: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
ac60: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
ac70: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
ac80: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
ac90: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
aca0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
acb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
acc0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
acd0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
ace0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
acf0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
ad00: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
ad10: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
ad20: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
ad30: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
ad40: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
ad50: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
ad60: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
ad70: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
ad80: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
ad90: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
ada0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
adb0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
adc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
add0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
ade0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
adf0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ae00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ae10: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ae20: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
ae30: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
ae40: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
ae50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
ae60: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
ae70: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
ae80: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ae90: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
aea0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
aeb0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
aec0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
aed0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
aee0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
aef0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
af00: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
af10: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
af20: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
af30: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
af40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
af50: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
af60: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
af70: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
af80: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
af90: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
afa0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
afb0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
afc0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
afd0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
afe0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
aff0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b000: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
b010: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
b020: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b030: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
b040: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
b050: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
b060: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b070: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
b080: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
b090: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
b0a0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
b0b0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
b0c0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
b0d0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
b0e0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
b0f0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
b100: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
b110: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
b120: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
b130: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
b140: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
b150: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
b160: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
b170: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
b180: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
b190: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
b1a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
b1b0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
b1c0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
b1d0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
b1e0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
b1f0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
b200: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
b210: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b220: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
b230: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b240: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
b250: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
b260: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
b270: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
b280: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b290: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b2a0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b2b0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b2c0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b2d0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b2e0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b2f0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b300: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b310: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
b320: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
b330: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
b340: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
b350: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
b360: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
b370: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
b380: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
b390: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
b3a0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b3b0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
b3c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b3d0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b3e0: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
b3f0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b400: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
b410: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
b420: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
b430: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
b440: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
b450: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
b460: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
b470: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
b480: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
b490: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
b4a0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
b4b0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
b4c0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
b4d0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
b4e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b4f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
b500: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
b510: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b520: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
b530: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
b540: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
b550: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
b560: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
b570: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
b580: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
b590: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
b5a0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
b5b0: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
b5c0: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
b5d0: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
b5e0: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
b5f0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
b600: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
b610: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
b620: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
b630: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
b640: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b650: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
b660: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
b670: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
b680: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
b690: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
b6a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
b6b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
b6c0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
b6d0: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
b6e0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  O               
b6f0: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
b700: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
b710: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
b720: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
b730: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
b740: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
b750: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
b760: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
b770: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
b780: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
b790: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
b7a0: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
b7b0: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
b7c0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
b7d0: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
b7e0: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
b7f0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
b800: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
b810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b820: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
b830: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
b840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b850: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
b860: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
b870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b880: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
b890: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
b8a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b8b0: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
b8c0: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
b8d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b8e0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
b8f0: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
b900: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b910: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
b920: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
b930: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b940: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
b950: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
b960: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
b970: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
b980: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
b990: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
b9a0: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
b9b0: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
b9c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
b9d0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
b9e0: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
b9f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
ba00: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
ba10: 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51     22.#define SQ
ba20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
ba30: 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _SET_HANDLE     
ba40: 20 20 32 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    23../*.** CAPI
ba50: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
ba60: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
ba70: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
ba80: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
ba90: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
baa0: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
bab0: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
bac0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
bad0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
bae0: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
baf0: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
bb00: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
bb10: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
bb20: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
bb30: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
bb40: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
bb50: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
bb60: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
bb70: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
bb80: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
bb90: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
bba0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
bbb0: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
bbc0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
bbd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
bbe0: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
bbf0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
bc00: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
bc10: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
bc20: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
bc30: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
bc40: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
bc50: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
bc60: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
bc70: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
bc80: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
bc90: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
bca0: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
bcb0: 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65  le system".  See
bcc0: 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56  .** the [VFS | V
bcd0: 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  FS documentation
bce0: 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e  ] for further in
bcf0: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
bd00: 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   The value of th
bd10: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
bd20: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20   is initially 1 
bd30: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
bd40: 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76  r in.** future v
bd50: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
bd60: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
bd70: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
bd80: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
bd90: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
bda0: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
bdb0: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e  is increased.  N
bdc0: 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72  ote that the str
bdd0: 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65  ucture.** of the
bde0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
bdf0: 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74  ect changes in t
be00: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
be10: 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  etween.** SQLite
be20: 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61   version 3.5.9 a
be30: 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74  nd 3.6.0 and yet
be40: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
be50: 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d  eld was not.** m
be60: 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  odified..**.** T
be70: 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c  he szOsFile fiel
be80: 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  d is the size of
be90: 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20   the subclassed 
bea0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a  [sqlite3_file].*
beb0: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
bec0: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
bed0: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
bee0: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
bef0: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
bf00: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
bf10: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73  .** Registered s
bf20: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
bf30: 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61  ts are kept on a
bf40: 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72   linked list for
bf50: 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e  med by.** the pN
bf60: 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ext pointer.  Th
bf70: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  e [sqlite3_vfs_r
bf80: 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e  egister()].** an
bf90: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  d [sqlite3_vfs_u
bfa0: 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74  nregister()] int
bfb0: 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74  erfaces manage t
bfc0: 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61  his list.** in a
bfd0: 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79   thread-safe way
bfe0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
bff0: 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65  vfs_find()] inte
c000: 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65  rface.** searche
c010: 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69  s the list.  Nei
c020: 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  ther the applica
c030: 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68  tion code nor th
c040: 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65  e VFS.** impleme
c050: 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  ntation should u
c060: 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  se the pNext poi
c070: 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
c080: 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74  pNext field is t
c090: 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e  he only field in
c0a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c0b0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68  .** structure th
c0c0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  at SQLite will e
c0d0: 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c  ver modify.  SQL
c0e0: 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63  ite will only ac
c0f0: 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66  cess.** or modif
c100: 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69  y this field whi
c110: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
c120: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
c130: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
c140: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
c150: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
c160: 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65  thing within the
c170: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c180: 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20  object once the 
c190: 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20  object has been 
c1a0: 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a  registered..**.*
c1b0: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
c1c0: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
c1d0: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
c1e0: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
c1f0: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
c200: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
c210: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  odules..**.** [[
c220: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
c230: 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  n]].** ^SQLite g
c240: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
c250: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
c260: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
c270: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
c280: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
c290: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
c2a0: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
c2b0: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
c2c0: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
c2d0: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
c2e0: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
c2f0: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
c300: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
c310: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
c320: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
c330: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
c340: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
c350: 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65  .** 11 alphanume
c360: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
c370: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
c380: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
c390: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
c3a0: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
c3b0: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
c3c0: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
c3d0: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
c3e0: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
c3f0: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
c400: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
c410: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
c420: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
c430: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
c440: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
c450: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
c460: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
c470: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
c480: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
c490: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
c4a0: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
c4b0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
c4c0: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
c4d0: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
c4e0: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
c4f0: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
c500: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
c510: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c520: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
c530: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
c540: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
c550: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
c560: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
c570: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c580: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
c590: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
c5a0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
c5b0: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
c5c0: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
c5d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
c5e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
c5f0: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
c600: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
c610: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
c620: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
c630: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
c640: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
c650: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
c660: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
c670: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
c680: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
c690: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
c6a0: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
c6b0: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
c6c0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
c6d0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
c6e0: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
c6f0: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
c700: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
c710: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
c720: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
c730: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
c740: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
c750: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
c760: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
c770: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
c780: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
c790: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
c7a0: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
c7b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
c7c0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
c7d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c7e0: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
c7f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
c800: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
c810: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c820: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
c830: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c840: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
c850: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
c860: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
c870: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
c880: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
c890: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
c8a0: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
c8b0: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
c8c0: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
c8d0: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
c8e0: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
c8f0: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
c900: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
c910: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
c920: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
c930: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
c940: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
c950: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
c960: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
c970: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
c980: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
c990: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
c9a0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
c9b0: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
c9c0: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
c9d0: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
c9e0: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
c9f0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
ca00: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
ca10: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
ca20: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
ca30: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
ca40: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
ca50: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
ca60: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
ca70: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
ca80: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
ca90: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
caa0: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
cab0: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
cac0: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
cad0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
cae0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
caf0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
cb00: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
cb10: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
cb20: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
cb30: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
cb40: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
cb50: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
cb60: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
cb70: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
cb80: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
cb90: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
cba0: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
cbb0: 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
cbc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
cbd0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
cbe0: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
cbf0: 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
cc00: 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
cc10: 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
cc20: 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
cc30: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
cc40: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
cc50: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
cc60: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
cc70: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
cc80: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
cc90: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
cca0: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
ccb0: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
ccc0: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
ccd0: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
cce0: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
ccf0: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
cd00: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
cd10: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
cd20: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
cd30: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
cd40: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
cd50: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
cd60: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
cd70: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
cd80: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
cd90: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
cda0: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
cdb0: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
cdc0: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
cdd0: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
cde0: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
cdf0: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
ce00: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
ce10: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
ce20: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
ce30: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
ce40: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
ce50: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
ce60: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
ce70: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
ce80: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
ce90: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
cea0: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
ceb0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
cec0: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
ced0: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
cee0: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
cef0: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
cf00: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
cf10: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
cf20: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
cf30: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
cf40: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
cf50: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
cf60: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
cf70: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
cf80: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
cf90: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
cfa0: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
cfb0: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
cfc0: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
cfd0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
cfe0: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
cff0: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
d000: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
d010: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
d020: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
d030: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
d040: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
d050: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41  [[sqlite3_vfs.xA
d060: 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20  ccess]].** ^The 
d070: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
d080: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
d090: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
d0a0: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
d0b0: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
d0c0: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
d0d0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
d0e0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
d0f0: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
d100: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
d110: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
d120: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
d130: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
d140: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d150: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
d160: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
d170: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
d180: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
d190: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
d1a0: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
d1b0: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
d1c0: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
d1d0: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
d1e0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
d1f0: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
d200: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
d210: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
d220: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
d230: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
d240: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
d250: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
d260: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
d270: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
d280: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
d290: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
d2a0: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
d2b0: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
d2c0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
d2d0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
d2e0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
d2f0: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
d300: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
d310: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
d320: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
d330: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
d340: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
d350: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
d360: 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  ), xCurrentTime(
d370: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
d380: 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e  imeInt64().** in
d390: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74  terfaces are not
d3a0: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
d3b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
d3c0: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
d3d0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
d3e0: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
d3f0: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
d400: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
d410: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
d420: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
d430: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
d440: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
d450: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
d460: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
d470: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
d480: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
d490: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
d4a0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
d4b0: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
d4c0: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
d4d0: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
d4e0: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
d4f0: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
d500: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
d510: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
d520: 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  .  ^The xCurrent
d530: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
d540: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
d550: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
d560: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
d570: 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a  e and time as.**
d580: 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
d590: 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65  t value..** ^The
d5a0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d5b0: 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  64() method retu
d5c0: 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67  rns, as an integ
d5d0: 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a  er, the Julian.*
d5e0: 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c  * Day Number mul
d5f0: 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30  tiplied by 86400
d600: 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20  000 (the number 
d610: 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
d620: 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72  in .** a 24-hour
d630: 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c   day).  .** ^SQL
d640: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
d650: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d660: 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67  64() method to g
d670: 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  et the current.*
d680: 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  * date and time 
d690: 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69  if that method i
d6a0: 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20  s available (if 
d6b0: 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72  iVersion is 2 or
d6c0: 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64   .** greater and
d6d0: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
d6e0: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
d6f0: 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c  L) and will fall
d700: 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72   back.** to xCur
d710: 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43  rentTime() if xC
d720: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d730: 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  ) is unavailable
d740: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65  ..**.** ^The xSe
d750: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78  tSystemCall(), x
d760: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  GetSystemCall(),
d770: 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d   and xNestSystem
d780: 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  Call() interface
d790: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65  s.** are not use
d7a0: 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20  d by the SQLite 
d7b0: 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74  core.  These opt
d7c0: 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ional interfaces
d7d0: 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a   are provided.**
d7e0: 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74   by some VFSes t
d7f0: 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73  o facilitate tes
d800: 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20  ting of the VFS 
d810: 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64  code. By overrid
d820: 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63  ing .** system c
d830: 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69  alls with functi
d840: 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f  ons under its co
d850: 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72  ntrol, a test pr
d860: 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d  ogram can.** sim
d870: 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64  ulate faults and
d880: 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e   error condition
d890: 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68  s that would oth
d8a0: 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63  erwise be diffic
d8b0: 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73  ult.** or imposs
d8c0: 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20  ible to induce. 
d8d0: 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74   The set of syst
d8e0: 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61  em calls that ca
d8f0: 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a  n be overridden.
d900: 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f  ** varies from o
d910: 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65  ne VFS to anothe
d920: 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20  r, and from one 
d930: 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73  version of the s
d940: 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a  ame VFS to the.*
d950: 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
d960: 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74  tions that use t
d970: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
d980: 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64  must be prepared
d990: 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61   for any.** or a
d9a0: 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ll of these inte
d9b0: 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c  rfaces to be NUL
d9c0: 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62  L or for their b
d9d0: 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67  ehavior to chang
d9e0: 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65  e.** from one re
d9f0: 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78  lease to the nex
da00: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
da10: 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70   must not attemp
da20: 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61  t to access.** a
da30: 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68  ny of these meth
da40: 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73  ods if the iVers
da50: 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69  ion of the VFS i
da60: 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a  s less than 3..*
da70: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
da80: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
da90: 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65  ite3_vfs;.typede
daa0: 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
dab0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f  _syscall_ptr)(vo
dac0: 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  id);.struct sqli
dad0: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
dae0: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
daf0: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
db00: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
db10: 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a   (currently 3) *
db20: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
db30: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
db40: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
db50: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
db60: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
db70: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
db80: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
db90: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
dba0: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
dbb0: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
dbc0: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
dbd0: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
dbe0: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
dbf0: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
dc00: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
dc10: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
dc20: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
dc30: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
dc40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
dc50: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
dc60: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
dc70: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dc80: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
dc90: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
dca0: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
dcb0: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
dcc0: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
dcd0: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
dce0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
dcf0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
dd00: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
dd10: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
dd20: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
dd30: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
dd40: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
dd50: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
dd60: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
dd70: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
dd80: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
dd90: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
dda0: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
ddb0: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
ddc0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ddd0: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
dde0: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
ddf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
de00: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
de10: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28  rrMsg);.  void (
de20: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
de30: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
de40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
de50: 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f  ol))(void);.  vo
de60: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
de70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
de80: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
de90: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
dea0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
deb0: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
dec0: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
ded0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
dee0: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
def0: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
df00: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
df10: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
df20: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
df30: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
df40: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
df50: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
df60: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
df70: 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f  e in version 1 o
df80: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
df90: 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66   object.  ** def
dfa0: 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20  inition.  Those 
dfb0: 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20  that follow are 
dfc0: 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e  added in version
dfd0: 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f   2 or later.  */
dfe0: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
dff0: 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69  tTimeInt64)(sqli
e000: 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65  te3_vfs*, sqlite
e010: 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a  3_int64*);.  /*.
e020: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
e030: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
e040: 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f  rsions 1 and 2 o
e050: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
e060: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68   object..  ** Th
e070: 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f  ose below are fo
e080: 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20  r version 3 and 
e090: 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20  greater..  */.  
e0a0: 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d  int (*xSetSystem
e0b0: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
e0c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e0d0: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
e0e0: 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73  yscall_ptr);.  s
e0f0: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
e100: 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43  tr (*xGetSystemC
e110: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
e120: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e130: 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63  Name);.  const c
e140: 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74  har *(*xNextSyst
e150: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e160: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e170: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20   *zName);.  /*. 
e180: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
e190: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
e1a0: 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20  sions 1 through 
e1b0: 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  3 of the sqlite_
e1c0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
e1d0: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
e1e0: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
e1f0: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
e200: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
e210: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
e220: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
e230: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a   this happens. .
e240: 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43    */.};../*.** C
e250: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e260: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
e270: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
e280: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
e290: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
e2a0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
e2b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
e2c0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e2d0: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
e2e0: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
e2f0: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
e300: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
e310: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
e320: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
e330: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
e340: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
e350: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
e360: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e370: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
e380: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
e390: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
e3a0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e3b0: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
e3c0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
e3d0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
e3e0: 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74  the named direct
e3f0: 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64  ory is both read
e400: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
e410: 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77  e.** (in other w
e420: 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63  ords, if files c
e430: 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d  an be added, rem
e440: 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65  oved, and rename
e450: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
e460: 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54  directory)..** T
e470: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
e480: 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74  _READWRITE const
e490: 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ant is currently
e4a0: 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68   used only by th
e4b0: 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65  e.** [temp_store
e4c0: 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
e4d0: 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20  a], though this 
e4e0: 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20  could change in 
e4f0: 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
e500: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
e510: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
e520: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
e530: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
e540: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
e550: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
e560: 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54  able.  The SQLIT
e570: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f  E_ACCESS_READ co
e580: 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72  nstant is.** cur
e590: 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74  rently unused, t
e5a0: 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62  hough it might b
e5b0: 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75  e used in a futu
e5c0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
e5d0: 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
e5e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
e5f0: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
e600: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e610: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20  ESS_READWRITE 1 
e620: 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41    /* Used by PRA
e630: 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64  GMA temp_store_d
e640: 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66  irectory */.#def
e650: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
e660: 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20  S_READ      2   
e670: 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a  /* Unused */../*
e680: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
e690: 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d  ags for the xShm
e6a0: 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a  Lock VFS method.
e6b0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
e6c0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ger constants de
e6d0: 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73  fine the various
e6e0: 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69   locking operati
e6f0: 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62  ons.** allowed b
e700: 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  y the xShmLock m
e710: 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65  ethod of [sqlite
e720: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20  3_io_methods].  
e730: 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  The.** following
e740: 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65   are the only le
e750: 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  gal combinations
e760: 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65   of flags to the
e770: 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  .** xShmLock met
e780: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
e790: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
e7a0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
e7b0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
e7c0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e7d0: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
e7e0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
e7f0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e800: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
e810: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
e820: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
e830: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
e840: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
e850: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65   </ul>.**.** Whe
e860: 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65  n unlocking, the
e870: 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20   same SHARED or 
e880: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d  EXCLUSIVE flag m
e890: 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20  ust be supplied 
e8a0: 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20  as.** was given 
e8b0: 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  on the correspon
e8c0: 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a  ding lock.  .**.
e8d0: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
e8e0: 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73  method can trans
e8f0: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e  ition between un
e900: 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45  locked and SHARE
e910: 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20  D or.** between 
e920: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43  unlocked and EXC
e930: 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e  LUSIVE.  It cann
e940: 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  ot transition be
e950: 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20  tween SHARED.** 
e960: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a  and EXCLUSIVE..*
e970: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e980: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  _SHM_UNLOCK     
e990: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
e9a0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20  TE_SHM_LOCK     
e9b0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
e9c0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20  LITE_SHM_SHARED 
e9d0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
e9e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
e9f0: 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a  SIVE    8../*.**
ea00: 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d   CAPI3REF: Maxim
ea10: 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65  um xShmLock inde
ea20: 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d  x.**.** The xShm
ea30: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b  Lock method on [
ea40: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ea50: 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75  ds] may use valu
ea60: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  es.** between 0 
ea70: 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62  and this upper b
ea80: 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66  ound as its "off
ea90: 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  set" argument..*
eaa0: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
eab0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74  e will never att
eac0: 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20  empt to acquire 
ead0: 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20  or release a.** 
eae0: 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20  lock outside of 
eaf0: 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64  this range.*/.#d
eb00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
eb10: 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a  _NLOCK        8.
eb20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
eb30: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
eb40: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
eb50: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
eb60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
eb70: 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69  routine initiali
eb80: 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  zes the.** SQLit
eb90: 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65  e library.  ^The
eba0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
ebb0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
ebc0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
ebd0: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
ebe0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
ebf0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ec00: 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ze()..** These r
ec10: 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69  outines are desi
ec20: 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70  gned to aid in p
ec30: 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
ec40: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75  ation and.** shu
ec50: 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65  tdown on embedde
ec60: 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b  d systems.  Work
ec70: 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74  station applicat
ec80: 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ions using.** SQ
ec90: 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f  Lite normally do
eca0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76   not need to inv
ecb0: 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68  oke either of th
ecc0: 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
ecd0: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
ece0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ecf0: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
ed00: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
ed10: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
ed20: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
ed30: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
ed40: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
ed50: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
ed60: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
ed70: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
ed80: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
ed90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
eda0: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
edb0: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
edc0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
edd0: 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66  .  ^(Only an eff
ede0: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
edf0: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
ee00: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
ee10: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
ee20: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
ee30: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
ee40: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
ee50: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
ee60: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73  e3_shutdown() is
ee70: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
ee80: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68  call if it is th
ee90: 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20  e first.** call 
eea0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
eeb0: 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20  own() since the 
eec0: 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  last sqlite3_ini
eed0: 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e  tialize().  ^(On
eee0: 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
eef0: 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
ef00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
ef10: 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
ef20: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
ef30: 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
ef40: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
ef50: 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
ef60: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
ef70: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
ef80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e  _initialize() in
ef90: 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61  terface is threa
efa0: 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74  dsafe, but sqlit
efb0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
efc0: 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71   is not.  The sq
efd0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
efe0: 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20   interface must 
eff0: 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66  only be called f
f000: 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  rom a.** single 
f010: 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65  thread.  All ope
f020: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
f030: 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65  ections] must be
f040: 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a   closed and all.
f050: 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
f060: 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62  resources must b
f070: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72  e deallocated pr
f080: 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a  ior to invoking.
f090: 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ** sqlite3_shutd
f0a0: 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  own()..**.** Amo
f0b0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
f0c0: 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   ^sqlite3_initia
f0d0: 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f  lize() will invo
f0e0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
f0f0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
f100: 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68  rly, ^sqlite3_sh
f110: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c  utdown().** will
f120: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f130: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
f140: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f150: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f160: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
f170: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
f180: 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d  ..** ^If for som
f190: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65  e reason, sqlite
f1a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f1b0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74  s unable to init
f1c0: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69  ialize.** the li
f1d0: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69  brary (perhaps i
f1e0: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  t is unable to a
f1f0: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64  llocate a needed
f200: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a   resource such.*
f210: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74  * as a mutex) it
f220: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72   returns an [err
f230: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74  or code] other t
f240: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  han [SQLITE_OK].
f250: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f260: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f270: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
f280: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
f290: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
f2a0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
f2b0: 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
f2c0: 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
f2d0: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
f2e0: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
f2f0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f300: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
f310: 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
f320: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
f330: 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
f340: 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
f350: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
f360: 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
f370: 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
f380: 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
f390: 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
f3a0: 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
f3b0: 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
f3c0: 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77  * already.  ^How
f3d0: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
f3e0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f3f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
f400: 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
f410: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
f420: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
f430: 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
f440: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f450: 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
f460: 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
f470: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
f480: 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
f490: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
f4a0: 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
f4b0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
f4c0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
f4d0: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
f4e0: 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
f4f0: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
f500: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
f510: 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
f520: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f530: 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
f540: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
f550: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
f560: 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
f570: 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
f580: 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
f590: 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
f5a0: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
f5b0: 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
f5c0: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
f5d0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f5e0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
f5f0: 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
f600: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
f610: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
f620: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
f630: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
f640: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
f650: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
f660: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
f670: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
f680: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
f690: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
f6a0: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
f6b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f6c0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
f6d0: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
f6e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f6f0: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
f700: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
f710: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
f720: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
f730: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
f740: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
f750: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
f760: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
f770: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
f780: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
f790: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
f7a0: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
f7b0: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
f7c0: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
f7d0: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
f7e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f7f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
f800: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
f810: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
f820: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
f830: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
f840: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
f850: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
f860: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
f870: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
f880: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f890: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
f8a0: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
f8b0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f8c0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
f8d0: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
f8e0: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
f8f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
f900: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
f910: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
f920: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
f930: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
f940: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
f950: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
f960: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
f970: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f980: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
f990: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
f9a0: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
f9b0: 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73  or Unix, Windows
f9c0: 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68  , or OS/2..** Wh
f9d0: 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64  en [custom build
f9e0: 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  s | built for ot
f9f0: 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a  her platforms].*
fa00: 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  * (using the [SQ
fa10: 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
fa20: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
fa30: 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
fa40: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
fa50: 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
fa60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
fa70: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
fa80: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
fa90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
faa0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
fab0: 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
fac0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
fad0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
fae0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
faf0: 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
fb00: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
fb10: 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
fb20: 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
fb30: 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
fb40: 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ure..*/.int sqli
fb50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
fb60: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
fb70: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
fb80: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
fb90: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74  _init(void);.int
fba0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fbb0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
fbc0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
fbd0: 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
fbe0: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
fbf0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
fc00: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
fc10: 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
fc20: 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
fc30: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
fc40: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
fc50: 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
fc60: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
fc70: 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
fc80: 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
fc90: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
fca0: 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
fcb0: 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
fcc0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
fcd0: 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
fce0: 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
fcf0: 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
fd00: 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
fd10: 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
fd20: 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
fd30: 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
fd40: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fd50: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
fd60: 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
fd70: 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
fd80: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
fd90: 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
fda0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
fdb0: 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
fdc0: 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
fdd0: 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
fde0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fdf0: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
fe00: 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
fe10: 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
fe20: 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
fe30: 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
fe40: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
fe50: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
fe60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
fe70: 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
fe80: 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
fe90: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
fea0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
feb0: 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
fec0: 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
fed0: 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
fee0: 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
fef0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
ff00: 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
ff10: 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
ff20: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
ff30: 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
ff40: 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
ff50: 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
ff60: 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
ff70: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
ff80: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
ff90: 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
ffa0: 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
ffb0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ffc0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
ffd0: 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
ffe0: 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
fff0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
10000 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
10010 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
10020 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
10030 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
10040 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
10050 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
10060 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
10070 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10080 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
10090 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
100a0 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
100b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
100c0 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
100d0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
100e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
100f0 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
10100 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
10110 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
10120 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
10130 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
10140 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
10150 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
10160 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  code]..*/.int sq
10170 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
10180 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
10190 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
101a0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
101b0 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  ections.**.** Th
101c0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
101d0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
101e0 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
101f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10200 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
10210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10220 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
10230 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
10240 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10250 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
10260 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
10270 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
10280 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
10290 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
102a0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
102b0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
102c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
102d0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
102e0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
102f0 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
10300 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
10310 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
10320 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10330 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
10340 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
10350 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
10360 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
10370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10380 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
10390 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
103a0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
103b0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
103c0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
103d0 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
103e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
103f0 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
10400 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
10410 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
10420 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
10430 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
10440 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10450 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
10460 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
10470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10480 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
10490 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
104a0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
104b0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
104c0 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
104d0 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
104e0 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
104f0 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
10500 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
10510 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
10520 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
10530 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
10540 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
10550 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
10560 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
10570 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10580 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
10590 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
105a0 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
105b0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
105c0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
105d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
105e0 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
105f0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
10600 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
10610 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
10620 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
10630 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
10640 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
10650 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
10660 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
10670 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
10680 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
10690 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
106a0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
106b0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
106c0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
106d0 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
106e0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
106f0 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
10700 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
10710 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
10720 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
10730 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
10740 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
10750 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
10760 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
10770 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
10780 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
10790 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
107a0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
107b0 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
107c0 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
107d0 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
107e0 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
107f0 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
10800 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10810 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
10820 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
10830 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
10840 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
10850 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
10860 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
10870 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
10880 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
10890 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
108a0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
108b0 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
108c0 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
108d0 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
108e0 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
108f0 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
10900 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
10910 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
10920 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
10930 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
10940 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
10950 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
10960 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
10970 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
10980 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
10990 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
109a0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
109b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
109c0 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
109d0 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
109e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
109f0 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
10a00 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
10a10 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
10a20 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
10a30 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
10a40 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
10a50 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
10a60 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
10a70 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
10a80 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
10a90 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
10aa0 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
10ab0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
10ac0 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
10ad0 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
10ae0 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
10af0 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
10b00 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
10b10 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
10b20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10b30 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
10b40 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
10b50 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
10b60 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
10b70 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
10b80 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
10b90 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
10ba0 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
10bb0 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
10bc0 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
10bd0 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
10be0 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
10bf0 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
10c00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10c10 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
10c20 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
10c30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
10c40 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
10c50 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
10c60 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
10c70 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
10c80 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
10c90 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
10ca0 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
10cb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
10cc0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
10cd0 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
10ce0 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
10cf0 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f  y allocator.  Fo
10d00 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
10d10 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
10d20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
10d30 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
10d40 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
10d50 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
10d60 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
10d70 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
10d80 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
10d90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
10da0 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
10db0 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
10dc0 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
10dd0 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
10de0 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
10df0 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
10e00 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
10e10 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
10e20 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
10e30 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
10e40 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
10e50 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
10e60 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
10e70 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
10e80 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
10e90 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
10ea0 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
10eb0 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
10ec0 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
10ed0 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
10ee0 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
10ef0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
10f00 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
10f10 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
10f20 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
10f30 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
10f40 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
10f50 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
10f60 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
10f70 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
10f80 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
10f90 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
10fa0 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
10fb0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
10fc0 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
10fd0 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
10fe0 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
10ff0 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
11000 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
11010 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
11020 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
11030 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
11040 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
11050 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
11060 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
11070 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
11080 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
11090 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
110a0 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
110b0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
110c0 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
110d0 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
110e0 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
110f0 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
11100 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
11110 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
11120 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
11130 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
11140 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11150 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
11160 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
11170 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
11180 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11190 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
111a0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
111b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
111c0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
111d0 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
111e0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
111f0 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
11200 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
11210 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
11220 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11230 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
11240 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
11250 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
11260 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
11270 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
11280 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
11290 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
112a0 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
112b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
112c0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
112d0 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
112e0 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
112f0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
11300 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
11310 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
11320 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
11330 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
11340 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11350 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
11360 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
11370 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
11380 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
11390 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
113a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
113b0 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
113c0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
113d0 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
113e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
113f0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
11400 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
11410 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
11420 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11430 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
11440 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
11450 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
11460 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
11470 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
11480 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
11490 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
114a0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
114b0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
114c0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
114d0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
114e0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
114f0 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
11500 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
11510 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
11520 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
11530 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
11540 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
11550 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
11560 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
11570 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
11580 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
11590 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
115a0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
115b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
115c0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
115d0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
115e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
115f0 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
11600 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
11610 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11620 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
11630 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11640 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
11650 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
11660 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
11670 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
11680 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
11690 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
116a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
116b0 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
116c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
116d0 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
116e0 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
116f0 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
11700 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
11710 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
11720 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
11730 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
11740 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11750 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11760 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11770 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11780 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11790 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
117a0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
117b0 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
117c0 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
117d0 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
117e0 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
117f0 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
11800 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
11810 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
11820 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
11830 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
11840 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
11850 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11860 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
11870 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
11880 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11890 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
118a0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
118b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
118c0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
118d0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
118e0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
118f0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11900 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11910 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
11920 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
11930 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
11940 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
11950 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
11960 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
11970 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
11980 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11990 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
119a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
119b0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
119c0 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
119d0 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
119e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
119f0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11a00 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
11a10 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
11a20 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
11a30 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
11a40 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
11a50 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
11a60 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
11a70 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
11a80 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
11a90 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
11aa0 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
11ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
11ac0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
11ad0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11ae0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11af0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11b00 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11b10 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11b20 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11b30 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
11b40 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
11b50 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
11b60 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
11b70 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
11b80 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11b90 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
11ba0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11bb0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
11bc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
11bd0 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
11be0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
11bf0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11c00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
11c10 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
11c20 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11c30 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
11c40 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
11c50 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
11c60 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
11c70 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
11c80 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
11c90 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
11ca0 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
11cb0 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
11cc0 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
11cd0 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
11ce0 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
11cf0 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
11d00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11d10 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11d20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
11d30 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
11d40 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
11d50 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
11d60 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11d70 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
11d80 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
11d90 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11da0 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
11db0 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
11dc0 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
11dd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
11de0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11df0 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
11e00 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
11e10 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
11e20 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
11e30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11e40 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
11e50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11e60 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
11e70 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
11e80 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
11e90 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11ea0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11eb0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11ec0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11ed0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11ee0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11ef0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11f00 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
11f10 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
11f20 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11f30 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
11f40 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11f50 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11f60 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11f70 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
11f80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11f90 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
11fa0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11fb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11fc0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
11fd0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11fe0 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
11ff0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
12000 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12010 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12020 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12030 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
12040 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
12050 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
12060 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12070 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
12080 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
12090 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
120a0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
120b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
120c0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
120d0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
120e0 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
120f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12100 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
12110 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
12120 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
12130 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
12140 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
12150 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12160 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12170 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
12180 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
12190 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
121a0 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
121b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
121c0 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
121d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
121e0 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
121f0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
12200 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12210 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
12220 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12230 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
12240 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12250 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12260 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12270 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12280 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
12290 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
122a0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
122b0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
122c0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
122d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
122e0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
122f0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
12300 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
12310 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
12320 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12330 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
12340 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
12350 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
12360 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12370 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
12380 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
12390 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
123a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
123b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
123c0 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
123d0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
123e0 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
123f0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
12400 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74  IG_MEMSTATUS opt
12410 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
12420 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
12430 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70  e int,.** interp
12440 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
12450 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
12460 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
12470 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a  e collection of.
12480 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
12490 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e  tion statistics.
124a0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
124b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
124c0 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  tics are.** disa
124d0 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
124e0 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
124f0 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
12500 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
12510 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
12520 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12530 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
12540 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
12550 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
12560 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12570 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
12580 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
12590 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
125a0 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
125b0 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
125c0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
125d0 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
125e0 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
125f0 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
12600 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
12610 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
12620 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
12630 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
12640 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
12650 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
12660 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
12670 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
12680 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12690 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
126a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
126b0 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
126c0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
126d0 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69  FIG_SCRATCH opti
126e0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
126f0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12700 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
12710 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73  te can use for s
12720 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
12730 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65  ^(There are thre
12740 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74  e arguments.** t
12750 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
12760 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e  SCRATCH:  A poin
12770 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
12780 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
12790 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
127a0 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
127b0 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
127c0 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
127d0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
127e0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
127f0 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
12800 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
12810 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
12820 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a  ations (N).)^.**
12830 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12840 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
12850 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
12860 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
12870 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
12880 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
12890 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
128a0 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d  e will not use m
128b0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
128c0 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
128d0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c   thread..** ^SQL
128e0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
128f0 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68  equest a scratch
12900 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
12910 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
12920 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
12930 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
12940 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
12950 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
12960 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
12970 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
12980 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
12990 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
129a0 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
129b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
129c0 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
129d0 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
129e0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
129f0 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  p>.** ^When the 
12a00 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76  application prov
12a10 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20  ides any amount 
12a20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  of scratch memor
12a30 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  y using.** SQLIT
12a40 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12a50 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20  , SQLite avoids 
12a60 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67  unnecessary larg
12a70 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
12a80 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61  lloc|heap alloca
12a90 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20  tions]..** This 
12aa0 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e  can help [Robson
12ab0 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d   proof|prevent m
12ac0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12ad0 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74   failures] due t
12ae0 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65  o heap.** fragme
12af0 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d  ntation in low-m
12b00 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73  emory embedded s
12b10 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  ystems..** </dd>
12b20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12b30 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
12b40 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12b50 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
12b60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
12b70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
12b80 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
12b90 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12ba0 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12bb0 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
12bc0 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20  can use for the 
12bd0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
12be0 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
12bf0 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63  ault page.** cac
12c00 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12c10 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
12c20 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
12c30 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
12c40 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
12c50 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
12c60 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12c70 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
12c80 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
12c90 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a  CONFIG_PCACHE2].
12ca0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12cb0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65   option..** ^The
12cc0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
12cd0 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
12ce0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12cf0 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
12d00 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
12d10 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
12d20 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
12d30 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
12d40 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
12d50 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
12d60 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
12d70 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
12d80 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
12d90 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
12da0 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
12db0 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
12dc0 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 73  nd 32768) plus s
12dd0 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
12de0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
12df0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
12e00 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
12e10 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
12e20 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
12e30 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
12e40 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ned using the [S
12e50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
12e60 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f  CHE_HDRSZ] optio
12e70 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  n .** to [sqlite
12e80 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20  3_config()]..** 
12e90 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
12ea0 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
12eb0 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
12ec0 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
12ed0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
12ee0 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
12ef0 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
12f00 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
12f10 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  d pointer to an 
12f20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
12f30 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74  lock of memory t
12f40 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61  hat.** is at lea
12f50 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
12f60 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69   memory, otherwi
12f70 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  se subsequent be
12f80 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
12f90 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69  efined..** ^SQLi
12fa0 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
12fb0 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
12fc0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
12fd0 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
12fe0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
12ff0 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
13000 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
13010 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
13020 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
13030 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
13040 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
13050 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
13060 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
13070 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
13080 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
13090 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
130a0 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
130b0 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
130c0 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ace.</dd>.**.** 
130d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
130e0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
130f0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
13100 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
13120 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
13130 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
13140 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
13150 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
13160 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
13170 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
13180 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13190 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
131a0 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
131b0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
131c0 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a  G_SCRATCH] and.*
131d0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
131e0 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
131f0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13200 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69  IG_HEAP option i
13210 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
13220 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
13230 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65  mpiled.** with e
13240 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
13250 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
13260 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
13270 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74  MEMSYS5] and ret
13280 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
13290 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65  ERROR] if invoke
132a0 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20  d otherwise..** 
132b0 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
132c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
132d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
132e0 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61  :.** An 8-byte a
132f0 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
13300 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
13310 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
13320 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
13330 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
13340 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13350 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
13360 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
13370 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13380 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
13390 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
133a0 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
133b0 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
133c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
133d0 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
133e0 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
133f0 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
13400 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
13410 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
13420 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
13430 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
13440 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
13450 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  ot NULL then the
13460 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
13470 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
13480 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
13490 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
134a0 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
134b0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
134c0 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
134d0 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
134e0 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
134f0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
13500 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
13510 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
13520 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
13530 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
13540 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
13550 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13560 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
13570 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
13580 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
13590 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
135a0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
135b0 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
135c0 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
135d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
135e0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
135f0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
13600 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13610 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13620 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
13630 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13640 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a  ment which is a.
13650 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
13660 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13670 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13680 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13690 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
136a0 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c  ent specifies al
136b0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
136c0 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
136d0 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a  es to be used.**
136e0 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75   in place the mu
136f0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
13700 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
13710 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
13720 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
13730 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
13740 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13750 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13760 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
13770 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
13780 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
13790 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
137a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
137b0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
137c0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
137d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
137e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
137f0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13800 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13810 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13820 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
13830 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
13840 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
13850 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13860 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
13870 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
13880 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13890 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
138a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
138b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
138c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
138d0 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
138e0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
138f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13900 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13910 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f  G_GETMUTEX optio
13920 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13930 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
13940 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
13950 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
13960 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13970 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
13980 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
13990 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
139a0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
139b0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
139c0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
139d0 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
139e0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
139f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
13a00 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
13a10 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
13a20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
13a30 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
13a40 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
13a50 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
13a60 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
13a70 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
13a80 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
13a90 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
13aa0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13ab0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13ac0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13ad0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13ae0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13af0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13b00 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
13b10 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
13b20 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
13b30 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
13b40 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
13b50 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13b60 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
13b70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13b80 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
13b90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
13ba0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
13bb0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
13bc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13bd0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13be0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13bf0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
13c00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13c10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13c20 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e  LOOKASIDE option
13c30 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
13c40 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
13c50 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75  ine.** the defau
13c60 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61  lt size of looka
13c70 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65  side memory on e
13c80 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
13c90 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
13ca0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13cb0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
13cc0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
13cd0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
13ce0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
13cf0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
13d00 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
13d10 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
13d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
13d30 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   ^(SQLITE_CONFIG
13d40 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65  _LOOKASIDE.** se
13d50 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c  ts the <i>defaul
13d60 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
13d70 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
13d80 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
13d90 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20  SIDE].** option 
13da0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
13db0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
13dc0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
13dd0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
13de0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
13df0 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
13e00 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
13e10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13e20 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
13e30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13e40 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
13e50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13e70 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
13e80 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13e90 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
13ea0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13eb0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
13ec0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
13ed0 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
13ee0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
13ef0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63  interface to a c
13f00 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
13f10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13f20 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61  )^.** ^SQLite ma
13f30 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
13f40 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  e [sqlite3_pcach
13f50 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
13f60 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ct.</dd>.**.** [
13f70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
13f80 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
13f90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13fa0 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
13fb0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
13fc0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13fd0 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
13fe0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13ff0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14000 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14010 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
14020 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
14030 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
14040 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65   of.** the curre
14050 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  nt page cache im
14060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
14070 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
14080 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
140a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
140b0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
140c0 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
140d0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
140e0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
140f0 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
14100 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
14110 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
14120 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14130 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
14140 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
14150 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
14160 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
14170 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
14180 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
14190 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
141a0 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
141b0 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
141c0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
141d0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
141e0 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
141f0 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
14200 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
14210 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
14220 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
14230 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
14240 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
14250 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
14260 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
14270 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
14280 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
14290 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
142a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
142b0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
142c0 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
142d0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
142e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
142f0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
14300 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
14310 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
14320 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
14330 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
14340 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
14350 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
14360 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
14370 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
14380 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14390 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
143a0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
143b0 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
143c0 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
143d0 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
143e0 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
143f0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
14400 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
14410 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
14420 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
14430 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
14440 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
14450 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
14460 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
14470 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
14480 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
14490 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
144a0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
144b0 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
144c0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
144d0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
144e0 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
144f0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
14500 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
14510 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
14520 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14530 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14540 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
14550 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
14560 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14570 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
14580 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14590 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
145a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
145b0 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  URI option takes
145c0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
145d0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a  nt of type int..
145e0 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  ** If non-zero, 
145f0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
14600 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
14610 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
14620 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
14630 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e  .** then URI han
14640 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14650 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
14660 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
14670 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e  s globally.** en
14680 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
14690 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b  ames passed to [
146a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
146b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
146c0 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
146d0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
146e0 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
146f0 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
14700 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
14710 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14720 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
14730 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
14740 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
14750 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
14760 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
14770 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
14780 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14790 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
147a0 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
147b0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
147c0 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
147d0 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
147e0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
147f0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14800 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
14810 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
14820 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
14830 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
14840 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
14850 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
14860 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
14870 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
14880 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
14890 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
148a0 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
148b0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
148c0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
148d0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
148e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
148f0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
14900 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
14910 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14920 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14930 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SCAN option take
14940 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
14950 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77  er.** argument w
14960 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
14970 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
14980 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
14990 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a  ble or disable.*
149a0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  * the use of cov
149b0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
149c0 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
149d0 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
149e0 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54  optimizer..** ^T
149f0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
14a00 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
14a10 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
14a20 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
14a30 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
14a40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14a50 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
14a60 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
14a70 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
14a80 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
14a90 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
14aa0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
14ab0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
14ac0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
14ad0 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
14ae0 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
14af0 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
14b00 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
14b10 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
14b20 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
14b30 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
14b40 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
14b50 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
14b60 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
14b70 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
14b80 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
14b90 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
14ba0 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
14bb0 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
14bc0 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
14bd0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
14be0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14bf0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
14c00 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14c10 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
14c20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14c30 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
14c40 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14c50 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
14c60 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
14c70 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
14c80 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
14c90 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
14ca0 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
14cb0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
14cc0 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
14cd0 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
14ce0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14cf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14d00 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
14d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
14d20 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
14d30 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
14d40 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
14d50 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14d60 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
14d70 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
14d80 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
14d90 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
14da0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14db0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
14dc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
14dd0 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
14de0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
14df0 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
14e00 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
14e10 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
14e20 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
14e30 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
14e40 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
14e50 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
14e60 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
14e70 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
14e80 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
14e90 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
14ea0 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
14eb0 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
14ec0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
14ed0 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
14ee0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14ef0 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
14f00 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14f10 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
14f20 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
14f30 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
14f40 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
14f50 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
14f60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
14f70 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
14f80 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
14f90 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14fa0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
14fb0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
14fc0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
14fd0 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
14fe0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
14ff0 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
15000 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
15010 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
15020 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
15030 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
15040 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
15050 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
15060 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
15070 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
15080 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
15090 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
150a0 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
150b0 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
150c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
150d0 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
150e0 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
150f0 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
15100 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
15110 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
15120 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
15130 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
15140 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
15150 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15160 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
15170 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
15180 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
15190 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
151a0 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
151b0 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
151c0 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
151d0 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
151e0 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
151f0 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
15200 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
15210 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
15220 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
15230 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
15240 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
15250 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
15260 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
15270 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15280 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
15290 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
152a0 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
152b0 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
152c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
152d0 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
152e0 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
152f0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15300 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77  d mmap size.** w
15310 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20  ill be silently 
15320 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63  truncated if nec
15330 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69  essary so that i
15340 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65  t does not excee
15350 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d the.** compile
15360 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
15370 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
15380 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
15390 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
153a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
153b0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
153c0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
153d0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
153e0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
153f0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
15400 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
15410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
15420 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
15430 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15440 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
15450 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15460 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
15470 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15480 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15490 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20  HEAPSIZE option 
154a0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
154b0 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a  e if SQLite is.*
154c0 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  * compiled for W
154d0 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20  indows with the 
154e0 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  [SQLITE_WIN32_MA
154f0 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOC] pre-proces
15500 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66  sor macro.** def
15510 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f  ined. ^SQLITE_CO
15520 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15530 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
15540 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
15550 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
15560 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
15570 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
15580 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
15590 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ..** </dl>.**.**
155a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
155b0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
155c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
155d0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
155e0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
155f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15600 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
15610 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
15620 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
15630 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
15640 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
15650 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
15660 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
15670 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
15680 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
15690 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
156a0 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
156b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
156c0 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
156d0 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
156e0 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
156f0 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
15700 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
15710 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
15720 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
15730 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c  version..** </dl
15740 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
15750 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
15760 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
15770 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
15780 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
15790 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
157a0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
157b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
157c0 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
157d0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
157e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
157f0 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
15800 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
15810 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
15820 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15830 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
15840 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
15850 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
15860 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15870 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
15880 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
15890 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
158a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
158b0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
158c0 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
158d0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
158e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
158f0 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
15900 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
15910 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
15920 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
15930 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
15940 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
15950 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
15960 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15970 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
15980 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
15990 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
159a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
159b0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
159c0 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
159d0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
159e0 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
159f0 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
15a00 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
15a10 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
15a20 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
15a30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
15a40 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
15a50 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
15a60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15a70 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
15a80 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
15a90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15aa0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
15ab0 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
15ac0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15ad0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
15ae0 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
15af0 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
15b00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15b10 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
15b20 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
15b30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15b40 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
15b50 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
15b60 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
15b70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15b80 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15b90 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
15ba0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
15bb0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
15bc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
15bd0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
15be0 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f  AN 20  /* int */
15bf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15c00 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20  CONFIG_SQLLOG   
15c10 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c      21  /* xSqll
15c20 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  og, void* */.#de
15c30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15c40 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  IG_MMAP_SIZE    
15c50 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69  22  /* sqlite3_i
15c60 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e  nt64, sqlite3_in
15c70 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t64 */.#define S
15c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
15c90 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20  32_HEAPSIZE     
15ca0 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   23  /* int nByt
15cb0 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
15cc0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15cd0 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32  E_HDRSZ        2
15ce0 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a  4  /* int *psz *
15cf0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
15d00 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
15d10 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
15d20 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
15d30 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
15d40 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
15d50 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
15d60 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15d70 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
15d80 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
15d90 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15da0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
15db0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
15dc0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
15dd0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
15de0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
15df0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
15e00 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
15e10 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
15e20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15e30 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
15e40 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
15e50 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
15e60 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
15e70 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
15e80 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15e90 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
15ea0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
15eb0 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
15ec0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15ed0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
15ee0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
15ef0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
15f00 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
15f10 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
15f20 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
15f30 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
15f40 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
15f50 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
15f60 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15f70 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
15f80 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
15f90 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
15fa0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
15fb0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
15fc0 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
15fd0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
15fe0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
15ff0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
16000 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16010 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
16020 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
16030 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16040 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
16050 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
16060 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
16070 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
16080 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
16090 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
160a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
160b0 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
160c0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
160d0 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
160e0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
160f0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
16100 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
16110 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
16120 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
16130 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16140 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
16150 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
16160 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
16170 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
16180 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
16190 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
161a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
161b0 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
161c0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
161d0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
161e0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
161f0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
16200 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
16210 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
16220 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
16230 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
16240 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
16250 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
16260 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
16270 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
16280 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
16290 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
162a0 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
162b0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
162c0 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
162d0 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
162e0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
162f0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
16300 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
16310 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
16320 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
16330 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
16340 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
16350 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
16360 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
16370 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
16380 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
16390 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
163a0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
163b0 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
163c0 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
163d0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
163e0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
163f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16400 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
16410 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
16420 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
16430 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
16440 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
16450 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
16460 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
16470 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
16480 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
16490 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
164a0 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
164b0 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
164c0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
164d0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
164e0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
164f0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
16500 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
16510 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
16520 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
16530 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
16540 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
16550 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
16560 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
16570 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
16580 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
16590 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
165a0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
165b0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
165c0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
165d0 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
165e0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
165f0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
16600 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
16610 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
16620 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
16630 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16640 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
16650 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
16660 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
16670 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
16680 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
16690 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
166a0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
166b0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
166c0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
166d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
166e0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
166f0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
16700 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
16710 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
16720 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
16730 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
16740 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
16750 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
16760 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
16770 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
16780 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
16790 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
167a0 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
167b0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
167c0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
167d0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
167e0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
167f0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
16800 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
16810 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
16820 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
16830 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
16840 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
16850 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
16860 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
16870 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
16880 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
16890 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
168a0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
168b0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
168c0 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
168d0 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
168e0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
168f0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
16900 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
16910 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
16920 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
16930 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
16940 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
16950 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
16960 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
16970 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
16980 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
16990 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
169a0 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
169b0 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
169c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
169d0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
169e0 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
169f0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
16a00 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
16a10 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
16a20 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
16a30 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
16a40 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
16a50 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
16a60 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
16a70 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
16a80 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
16a90 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
16aa0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
16ab0 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
16ac0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
16ad0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
16ae0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
16af0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
16b00 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
16b10 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
16b20 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
16b30 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
16b40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
16b50 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
16b60 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
16b70 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
16b80 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
16b90 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
16ba0 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
16bb0 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74  in most SQLite t
16bc0 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f  ables (except fo
16bd0 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  r [WITHOUT ROWID
16be0 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73  ] tables).** has
16bf0 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
16c00 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
16c10 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
16c20 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
16c30 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
16c40 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
16c50 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
16c60 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
16c70 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
16c80 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
16c90 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
16ca0 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
16cb0 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
16cc0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
16cd0 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
16ce0 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
16cf0 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
16d00 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
16d10 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
16d20 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
16d30 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
16d40 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
16d50 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  he sqlite3_last_
16d60 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
16d70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
16d80 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
16d90 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65   the .** most re
16da0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
16db0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
16dc0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
16dd0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
16de0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
16df0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e  nnection D..** ^
16e00 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
16e10 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
16e20 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f  les are not reco
16e30 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  rded..** ^If no 
16e40 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16e50 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
16e60 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65  tables.** have e
16e70 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
16e80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
16e90 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74  nection D, .** t
16ea0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  hen sqlite3_last
16eb0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
16ec0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
16ed0 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
16ee0 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
16ef0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
16f00 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
16f10 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
16f20 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
16f30 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
16f40 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
16f50 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
16f60 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
16f70 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
16f80 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
16f90 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
16fa0 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
16fb0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
16fc0 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
16fd0 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
16fe0 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
16ff0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
17000 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
17010 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
17020 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
17030 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
17040 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
17050 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
17060 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
17070 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
17080 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
17090 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
170a0 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
170b0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
170c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
170d0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
170e0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
170f0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
17100 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
17110 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
17120 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
17130 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
17140 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
17150 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
17160 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
17170 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
17180 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
17190 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
171a0 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
171b0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
171c0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
171d0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
171e0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
171f0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
17200 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
17210 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
17220 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
17230 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
17240 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
17250 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
17260 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
17270 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
17280 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
17290 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
172a0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
172b0 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
172c0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
172d0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
172e0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
172f0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
17300 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
17310 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
17320 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
17330 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
17340 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
17350 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
17360 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
17370 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
17380 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
17390 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
173a0 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
173b0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
173c0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
173d0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
173e0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
173f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
17400 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
17410 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
17420 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
17430 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
17440 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
17450 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17460 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
17470 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
17480 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
17490 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
174a0 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
174b0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
174c0 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
174d0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
174e0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
174f0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
17500 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
17510 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
17520 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
17530 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17540 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17550 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
17560 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64  dified, inserted
17570 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
17580 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
17590 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
175a0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
175b0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
175c0 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ent on the datab
175d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
175e0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
175f0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  only parameter..
17600 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  ** ^Executing an
17610 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
17620 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
17630 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  es not modify th
17640 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
17650 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
17660 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  tion..**.** ^Onl
17670 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64  y changes made d
17680 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49  irectly by the I
17690 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
176a0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
176b0 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  t are.** conside
176c0 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20  red - auxiliary 
176d0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
176e0 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  y [CREATE TRIGGE
176f0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a  R | triggers], .
17700 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
17710 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50  actions] or [REP
17720 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
17730 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20   resolution are 
17740 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
17750 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61  .** Changes to a
17760 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
17770 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a  ntercepted by .*
17780 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  * [INSTEAD OF tr
17790 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20  igger | INSTEAD 
177a0 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65  OF triggers] are
177b0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54   not counted. ^T
177c0 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74  he value .** ret
177d0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
177e0 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64  _changes() immed
177f0 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20  iately after an 
17800 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
17810 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61  r .** DELETE sta
17820 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20  tement run on a 
17830 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a  view is always z
17840 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65  ero. Only change
17850 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a  s made to real .
17860 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f  ** tables are co
17870 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  unted..**.** Thi
17880 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d  ngs are more com
17890 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20  plicated if the 
178a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
178b0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  ) function is.**
178c0 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20   executed while 
178d0 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
178e0 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68  m is running. Th
178f0 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66  is may happen if
17900 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20   the.** program 
17910 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65  uses the [change
17920 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
17930 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74  ], or if some ot
17940 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  her callback.** 
17950 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  function invokes
17960 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
17970 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73  () directly. Ess
17980 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a  entially:.** .**
17990 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
179a0 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e  ^(Before enterin
179b0 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  g a trigger prog
179c0 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65  ram the value re
179d0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
179e0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e      sqlite3_chan
179f0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
17a00 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74  s saved. After t
17a10 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
17a20 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61  am .**        ha
17a30 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20  s finished, the 
17a40 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69  original value i
17a50 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a  s restored.)^.**
17a60 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69   .**   <li> ^(Wi
17a70 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70  thin a trigger p
17a80 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45  rogram each INSE
17a90 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44  RT, UPDATE and D
17aa0 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20  ELETE .**       
17ab0 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20   statement sets 
17ac0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17ad0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
17ae0 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
17af0 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69     upon completi
17b00 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66  on as normal. Of
17b10 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61   course, this va
17b20 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63  lue will not inc
17b30 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  lude .**        
17b40 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66  any changes perf
17b50 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69  ormed by sub-tri
17b60 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71  ggers, as the sq
17b70 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
17b80 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65  .**        value
17b90 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61   will be saved a
17ba0 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65  nd restored afte
17bb0 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67  r each sub-trigg
17bc0 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a  er has run.)^.**
17bd0 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54   </ul>.** .** ^T
17be0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
17bf0 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20  f the changes() 
17c00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72  SQL function (or
17c10 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65   similar) is use
17c20 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
17c30 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
17c40 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
17c50 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
17c60 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65  igger, it .** re
17c70 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
17c80 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  as set when the 
17c90 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e  calling statemen
17ca0 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e  t began executin
17cb0 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  g..** ^If it is 
17cc0 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  used by the seco
17cd0 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  nd or subsequent
17ce0 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20   such statement 
17cf0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
17d00 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68   .** program, th
17d10 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17d20 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75   reflects the nu
17d30 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
17d40 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
17d50 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54   previous INSERT
17d60 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
17d70 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
17d80 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69  hin the same tri
17d90 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  gger..**.** See 
17da0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
17db0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
17dc0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
17dd0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
17de0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
17df0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
17e00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
17e10 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
17e20 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
17e30 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
17e40 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
17e50 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
17e60 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
17e70 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
17e80 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
17e90 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
17ea0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
17eb0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
17ec0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
17ed0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
17ee0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17ef0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
17f00 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
17f10 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
17f20 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
17f30 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
17f40 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
17f50 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
17f60 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
17f70 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
17f80 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
17f90 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
17fa0 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
17fb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17fc0 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
17fd0 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
17fe0 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
17ff0 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
18000 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
18010 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
18020 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
18030 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
18040 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
18050 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
18060 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
18070 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
18080 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
18090 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
180a0 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
180b0 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
180c0 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
180d0 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
180e0 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
180f0 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
18100 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
18110 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
18120 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
18130 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
18140 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
18150 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
18160 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
18170 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
18180 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
18190 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
181a0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
181b0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
181c0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
181d0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
181e0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
181f0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
18200 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
18210 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18220 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
18230 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
18240 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
18250 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
18260 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
18270 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
18280 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
18290 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
182a0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
182b0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
182c0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
182d0 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
182e0 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  ning Query.**.**
182f0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
18300 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
18310 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
18320 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
18330 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
18340 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
18350 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
18360 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
18370 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
18380 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
18390 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
183a0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
183b0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
183c0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
183d0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
183e0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
183f0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
18400 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
18410 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
18420 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
18430 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
18440 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
18450 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
18460 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
18470 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
18480 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
18490 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
184a0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
184b0 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
184c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
184d0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
184e0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
184f0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
18500 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
18510 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
18520 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
18530 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
18540 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
18550 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
18560 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18570 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
18580 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
18590 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
185a0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
185b0 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
185c0 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
185d0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
185e0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
185f0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
18600 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
18610 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
18620 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
18630 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
18640 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
18650 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
18660 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
18670 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
18680 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
18690 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
186a0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
186b0 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
186c0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
186d0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
186e0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
186f0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
18700 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
18710 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
18720 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
18730 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
18740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18750 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
18760 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
18770 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
18780 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
18790 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
187a0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
187b0 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
187c0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
187d0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
187e0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
187f0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
18800 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
18810 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
18820 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18830 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
18840 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
18850 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
18860 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
18870 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
18880 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
18890 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
188a0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
188b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
188c0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
188d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
188e0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
188f0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
18900 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
18910 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
18920 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
18930 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
18940 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
18950 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
18960 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
18970 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
18980 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
18990 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
189a0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
189b0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
189c0 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
189d0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
189e0 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
189f0 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
18a00 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
18a10 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
18a20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
18a30 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
18a40 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
18a50 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
18a60 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
18a70 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
18a80 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
18a90 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
18aa0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
18ab0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
18ac0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
18ad0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
18ae0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
18af0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
18b00 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
18b10 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
18b20 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
18b30 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
18b40 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
18b50 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
18b60 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
18b70 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
18b80 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
18b90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
18ba0 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
18bb0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
18bc0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
18bd0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
18be0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
18bf0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
18c00 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
18c10 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
18c20 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
18c30 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
18c40 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
18c50 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
18c60 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
18c70 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
18c80 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
18c90 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
18ca0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
18cb0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
18cc0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
18cd0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
18ce0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
18cf0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
18d00 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
18d10 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
18d20 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
18d30 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
18d40 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
18d50 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
18d60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
18d70 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
18d80 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
18d90 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
18da0 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
18db0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
18dc0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
18dd0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
18de0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
18df0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
18e00 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
18e10 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
18e20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
18e30 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
18e40 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
18e50 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
18e60 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
18e70 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
18e80 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
18e90 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
18ea0 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
18eb0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
18ec0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
18ed0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
18ee0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
18ef0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
18f00 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
18f10 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
18f20 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
18f30 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
18f40 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
18f50 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
18f60 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
18f70 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
18f80 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
18f90 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
18fa0 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
18fb0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
18fc0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
18fd0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
18fe0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18ff0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
19000 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
19010 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
19020 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
19030 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
19040 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
19050 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
19060 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
19070 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
19080 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
19090 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
190a0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
190b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
190c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
190d0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
190e0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
190f0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
19100 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
19110 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
19120 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e  lback} {busy han
19130 64 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dler}.**.** ^The
19140 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
19150 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
19160 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
19170 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
19180 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
19190 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
191a0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
191b0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
191c0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
191d0 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
191e0 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
191f0 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
19200 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
19210 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
19220 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
19230 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
19240 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
19250 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
19260 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
19270 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
19280 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
19290 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
192a0 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
192b0 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
192c0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
192d0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
192e0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
192f0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
19300 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
19310 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
19320 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
19330 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
19340 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
19350 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
19360 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
19370 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
19380 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
19390 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
193a0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
193b0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
193c0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
193d0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
193e0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
193f0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
19400 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
19410 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
19420 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
19430 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
19440 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
19450 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
19460 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19470 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
19480 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
19490 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
194a0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
194b0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
194c0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
194d0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
194e0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
194f0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
19500 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
19510 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
19520 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
19530 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
19540 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
19550 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19560 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
19570 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
19580 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
19590 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
195a0 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
195b0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
195c0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
195d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
195e0 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
195f0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
19600 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
19610 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
19620 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
19630 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
19640 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
19650 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
19660 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
19670 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
19680 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
19690 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
196a0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
196b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
196c0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
196d0 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
196e0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
196f0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
19700 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
19710 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
19720 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
19730 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
19740 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
19750 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
19760 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
19770 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
19780 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
19790 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
197a0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
197b0 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
197c0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
197d0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
197e0 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
197f0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
19800 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
19810 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
19820 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
19830 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
19840 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
19850 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
19860 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
19870 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
19880 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
19890 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
198a0 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
198b0 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
198c0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
198d0 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
198e0 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
198f0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
19900 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
19910 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
19920 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
19930 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
19940 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
19950 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
19960 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
19970 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
19980 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
19990 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
199a0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
199b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
199c0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
199d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
199e0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
199f0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
19a00 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
19a10 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
19a20 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
19a30 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
19a40 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
19a50 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
19a60 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
19a70 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
19a80 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
19a90 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
19aa0 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
19ab0 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
19ac0 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
19ad0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
19ae0 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
19af0 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
19b00 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
19b10 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
19b20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19b30 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
19b40 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
19b50 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
19b60 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
19b70 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
19b80 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
19b90 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
19ba0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
19bb0 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
19bc0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
19bd0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
19be0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19bf0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
19c00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
19c10 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
19c20 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
19c30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
19c40 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
19c50 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
19c60 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
19c70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19c80 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
19c90 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
19ca0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
19cb0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
19cc0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
19cd0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
19ce0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
19cf0 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
19d00 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
19d10 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
19d20 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
19d30 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
19d40 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
19d50 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
19d60 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
19d70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
19d80 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
19d90 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
19da0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
19db0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
19dc0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
19dd0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
19de0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19df0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
19e00 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
19e10 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
19e20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
19e30 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
19e40 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
19e50 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
19e60 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
19e70 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
19e80 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
19e90 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
19ea0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
19eb0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
19ec0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
19ed0 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
19ee0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
19ef0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
19f00 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
19f10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
19f20 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
19f30 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
19f40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
19f50 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
19f60 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
19f70 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
19f80 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
19f90 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69  sy_timeout].*/.i
19fa0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
19fb0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
19fc0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
19fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
19fe0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
19ff0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1a000 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
1a010 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
1a020 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
1a030 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
1a040 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1a050 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
1a060 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1a070 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
1a080 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
1a090 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
1a0a0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
1a0b0 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
1a0c0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
1a0d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
1a0e0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
1a0f0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
1a100 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
1a110 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
1a120 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
1a130 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
1a140 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
1a150 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
1a160 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
1a170 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
1a180 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
1a190 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
1a1a0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
1a1b0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
1a1c0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
1a1d0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
1a1e0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
1a1f0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
1a200 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
1a210 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
1a220 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
1a230 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1a240 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
1a250 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
1a260 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1a270 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
1a280 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
1a290 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
1a2a0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
1a2b0 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
1a2c0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
1a2d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1a2e0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
1a2f0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
1a300 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
1a310 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
1a320 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
1a330 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
1a340 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
1a350 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
1a360 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
1a370 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
1a380 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
1a390 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1a3a0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
1a3b0 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
1a3c0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1a3d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1a3e0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1a3f0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
1a400 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
1a410 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1a420 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
1a430 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
1a440 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
1a450 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
1a460 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
1a470 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
1a480 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
1a490 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
1a4a0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1a4b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
1a4c0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
1a4d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
1a4e0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
1a4f0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
1a500 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1a510 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1a520 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1a530 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
1a540 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
1a550 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a560 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
1a570 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
1a580 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
1a590 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
1a5a0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
1a5b0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
1a5c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1a5d0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
1a5e0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
1a5f0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
1a600 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
1a610 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
1a620 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
1a630 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
1a640 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
1a650 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
1a660 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
1a670 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
1a680 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
1a690 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
1a6a0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a6b0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a6c0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
1a6d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a6e0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
1a6f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a700 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
1a710 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
1a720 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
1a730 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
1a740 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a750 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
1a760 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a770 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
1a780 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a790 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
1a7a0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
1a7b0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
1a7c0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
1a7d0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1a7e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1a7f0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
1a800 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
1a810 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1a820 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1a830 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1a840 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1a850 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1a860 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1a870 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1a880 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1a890 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1a8a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1a8b0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1a8c0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1a8d0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1a8e0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1a8f0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1a900 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1a910 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1a920 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1a930 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1a940 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1a950 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1a960 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1a970 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1a980 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1a990 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1a9a0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1a9b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1a9c0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1a9d0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a9e0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1a9f0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1aa00 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1aa10 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1aa20 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1aa30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1aa40 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1aa50 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1aa60 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1aa70 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1aa80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1aa90 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1aaa0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1aab0 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1aac0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1aad0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1aae0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1aaf0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1ab00 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1ab10 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1ab20 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1ab30 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1ab40 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1ab50 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1ab60 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1ab70 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1ab80 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1ab90 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1aba0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1abb0 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1abc0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1abd0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1abe0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1abf0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1ac00 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1ac10 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1ac20 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1ac30 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
1ac40 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
1ac50 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
1ac60 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1ac70 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
1ac80 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1ac90 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
1aca0 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
1acb0 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
1acc0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
1acd0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
1ace0 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
1acf0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
1ad00 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1ad10 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
1ad20 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
1ad30 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
1ad40 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1ad50 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
1ad60 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1ad70 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
1ad80 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
1ad90 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
1ada0 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
1adb0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1adc0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1add0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1ade0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1adf0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1ae00 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1ae10 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1ae20 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1ae30 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1ae40 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1ae50 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1ae60 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1ae70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ae80 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1ae90 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1aea0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1aeb0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1aec0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1aed0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1aee0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1aef0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1af00 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1af10 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1af20 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1af30 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1af40 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1af50 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1af60 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1af70 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1af80 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1af90 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1afa0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1afb0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1afc0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1afd0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1afe0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1aff0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1b000 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1b010 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1b020 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1b030 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1b040 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1b050 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1b060 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1b070 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1b080 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1b090 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1b0a0 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1b0b0 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1b0c0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1b0d0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1b0e0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1b0f0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1b100 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1b110 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1b120 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1b130 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1b140 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1b150 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1b160 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1b170 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1b180 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1b190 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1b1a0 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1b1b0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1b1c0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1b1d0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1b1e0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1b1f0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1b200 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1b210 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1b220 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1b230 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1b240 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1b250 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1b260 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1b270 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1b280 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1b290 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1b2a0 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1b2b0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1b2c0 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1b2d0 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1b2e0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1b2f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1b300 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1b310 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1b320 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1b330 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1b340 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1b350 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1b360 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1b370 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1b380 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1b390 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1b3a0 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1b3b0 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1b3c0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1b3d0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1b3e0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1b3f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b400 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1b410 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1b420 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1b430 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b440 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1b450 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1b460 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1b470 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1b480 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1b490 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1b4a0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1b4b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1b4c0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1b4d0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1b4e0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1b4f0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1b500 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1b510 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
1b520 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1b530 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1b540 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1b550 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1b560 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1b570 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1b580 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1b590 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1b5a0 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1b5b0 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1b5c0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1b5d0 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1b5e0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1b5f0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1b600 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1b610 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1b620 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1b630 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1b640 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1b650 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1b660 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1b670 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1b680 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1b690 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1b6a0 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1b6b0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1b6c0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1b6d0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1b6e0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1b6f0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1b700 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b710 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1b720 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1b730 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1b740 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1b750 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b760 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1b770 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1b780 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1b790 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1b7a0 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1b7b0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1b7c0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1b7d0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1b7e0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1b7f0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1b800 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1b810 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1b820 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1b830 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1b840 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1b850 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1b860 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1b870 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1b880 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1b890 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1b8a0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1b8b0 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1b8c0 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1b8d0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b8e0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1b8f0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1b900 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1b910 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1b920 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1b930 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1b940 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1b950 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b960 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1b970 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1b980 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1b990 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1b9a0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b9b0 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1b9c0 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1b9d0 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1b9e0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1b9f0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1ba00 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1ba10 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1ba20 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1ba30 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1ba40 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1ba50 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1ba60 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1ba70 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1ba80 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1ba90 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1baa0 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1bab0 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1bac0 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1bad0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1bae0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1baf0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1bb00 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1bb10 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1bb20 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1bb30 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1bb40 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1bb50 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1bb60 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1bb70 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1bb80 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1bb90 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1bba0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1bbb0 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1bbc0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1bbd0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1bbe0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1bbf0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1bc00 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1bc10 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1bc20 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1bc30 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1bc40 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1bc50 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1bc60 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1bc70 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1bc80 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1bc90 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1bca0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1bcb0 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1bcc0 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1bcd0 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1bce0 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1bcf0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1bd00 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1bd10 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1bd20 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1bd30 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1bd40 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1bd50 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
1bd60 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1bd70 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1bd80 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1bd90 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1bda0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1bdb0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
1bdc0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1bdd0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1bde0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1bdf0 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
1be00 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1be10 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
1be20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1be30 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
1be40 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
1be50 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
1be60 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
1be70 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
1be80 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
1be90 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
1bea0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
1beb0 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
1bec0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
1bed0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
1bee0 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
1bef0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
1bf00 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1bf10 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
1bf20 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
1bf30 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
1bf40 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
1bf50 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
1bf60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1bf70 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
1bf80 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1bf90 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
1bfa0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
1bfb0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
1bfc0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
1bfd0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
1bfe0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1bff0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
1c000 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
1c010 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
1c020 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
1c030 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1c040 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
1c050 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
1c060 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1c070 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
1c080 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
1c090 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
1c0a0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1c0b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
1c0c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1c0d0 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73  N) routine works
1c0e0 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71   just like.** sq
1c0f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
1c100 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
1c110 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d   an unsigned 64-
1c120 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74  bit integer inst
1c130 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e  ead.** of a sign
1c140 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  ed 32-bit intege
1c150 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
1c160 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
1c170 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
1c180 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
1c190 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1c1a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1c1b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1c1c0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
1c1d0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
1c1e0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
1c1f0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1c200 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
1c210 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
1c220 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
1c230 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1c240 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
1c250 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
1c260 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1c270 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
1c280 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
1c290 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
1c2a0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
1c2b0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
1c2c0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
1c2d0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
1c2e0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
1c2f0 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
1c300 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
1c310 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1c320 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
1c330 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
1c340 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
1c350 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1c360 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
1c370 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
1c380 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
1c390 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
1c3a0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
1c3b0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
1c3c0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1c3d0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1c3e0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
1c3f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c400 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74  realloc(X,N) int
1c410 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1c420 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1c430 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1c440 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61  cation X to be a
1c450 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e  t least N bytes.
1c460 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61  .** ^If the X pa
1c470 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1c480 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a  e3_realloc(X,N).
1c490 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
1c4a0 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
1c4b0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
1c4c0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
1c4d0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1c4e0 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  (N)..** ^If the 
1c4f0 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  N parameter to s
1c500 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1c510 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  ,N) is zero or.*
1c520 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
1c530 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1c540 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
1c550 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
1c560 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a  qlite3_free(X)..
1c570 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c  ** ^sqlite3_real
1c580 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1c590 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1c5a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c5b0 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1c5c0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1c5d0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75   or NULL if insu
1c5e0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1c5f0 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
1c600 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1c610 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1c620 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1c630 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1c640 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1c650 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1c660 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1c670 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1c680 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1c690 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1c6a0 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70  c(X,N) and the p
1c6b0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1c6c0 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
1c6d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c6e0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55  (X,N) returns NU
1c6f0 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69  LL and N is posi
1c700 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a  tive, then the.*
1c710 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  * prior allocati
1c720 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  on is not freed.
1c730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c740 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c  te3_realloc64(X,
1c750 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  N) interfaces wo
1c760 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a  rks the same as.
1c770 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
1c780 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74  oc(X,N) except t
1c790 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69  hat N is a 64-bi
1c7a0 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
1c7b0 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
1c7c0 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64   a 32-bit signed
1c7d0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
1c7e0 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72  ^If X is a memor
1c7f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65  y allocation pre
1c800 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
1c810 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1c820 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1c830 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73  e3_malloc64(), s
1c840 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c850 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  , or sqlite3_rea
1c860 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a  lloc64(), then.*
1c870 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1c880 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  X) returns the s
1c890 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f  ize of that memo
1c8a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e  ry allocation in
1c8b0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20   bytes..** ^The 
1c8c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1c8d0 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  y sqlite3_msize(
1c8e0 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  X) might be larg
1c8f0 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62  er than the numb
1c900 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72  er.** of bytes r
1c910 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20  equested when X 
1c920 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20  was allocated.  
1c930 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20  ^If X is a NULL 
1c940 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20  pointer then.** 
1c950 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1c960 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20   returns zero.  
1c970 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73  If X points to s
1c980 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73  omething that is
1c990 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69   not.** the begi
1c9a0 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20  nning of memory 
1c9b0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69  allocation, or i
1c9c0 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  f it points to a
1c9d0 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c   formerly.** val
1c9e0 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  id memory alloca
1c9f0 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f  tion that has no
1ca00 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68  w been freed, th
1ca10 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
1ca20 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73  ** of sqlite3_ms
1ca30 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69  ize(X) is undefi
1ca40 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79  ned and possibly
1ca50 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
1ca60 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
1ca70 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1ca80 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65  malloc(), sqlite
1ca90 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  3_realloc(),.** 
1caa0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1cab0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
1cac0 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69  realloc64().** i
1cad0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
1cae0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
1caf0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
1cb00 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
1cb10 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
1cb20 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
1cb30 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
1cb40 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
1cb50 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1cb60 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
1cb70 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
1cb80 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
1cb90 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
1cba0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
1cbb0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
1cbc0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
1cbd0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
1cbe0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
1cbf0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
1cc00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
1cc10 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
1cc20 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
1cc30 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
1cc40 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
1cc50 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1cc60 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
1cc70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
1cc80 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
1cc90 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
1cca0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
1ccb0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
1ccc0 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
1ccd0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1cce0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
1ccf0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
1cd00 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
1cd10 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
1cd20 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
1cd30 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
1cd40 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
1cd50 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
1cd60 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
1cd70 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
1cd80 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
1cd90 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1cda0 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
1cdb0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
1cdc0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
1cdd0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
1cde0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
1cdf0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
1ce00 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
1ce10 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
1ce20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
1ce30 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
1ce40 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
1ce50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1ce60 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1ce70 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
1ce80 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
1ce90 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
1cea0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
1ceb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1cec0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1ced0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
1cee0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
1cef0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
1cf00 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1cf10 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
1cf20 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
1cf30 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
1cf40 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
1cf50 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
1cf60 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
1cf70 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
1cf80 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1cf90 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
1cfa0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
1cfb0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
1cfc0 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74  3_malloc64(sqlit
1cfd0 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64  e3_uint64);.void
1cfe0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1cff0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
1d000 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1d010 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71  lloc64(void*, sq
1d020 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
1d030 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1d040 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33  (void*);.sqlite3
1d050 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
1d060 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  msize(void*);../
1d070 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1d080 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
1d090 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
1d0a0 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
1d0b0 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
1d0c0 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
1d0d0 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
1d0e0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
1d0f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
1d100 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1d110 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
1d120 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
1d130 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
1d140 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
1d150 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d160 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
1d170 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1d180 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
1d190 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1d1a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1d1b0 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
1d1c0 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
1d1d0 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
1d1e0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
1d1f0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1d200 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1d210 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
1d220 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
1d230 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
1d240 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1d250 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
1d260 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1d270 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
1d280 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
1d290 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1d2a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1d2b0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1d2c0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1d2d0 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
1d2e0 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
1d2f0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
1d300 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
1d310 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1d320 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
1d330 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
1d340 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
1d350 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
1d360 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
1d370 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
1d380 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
1d390 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
1d3a0 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
1d3b0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
1d3c0 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
1d3d0 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
1d3e0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1d3f0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
1d400 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
1d410 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
1d420 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1d430 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
1d440 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1d450 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
1d460 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1d470 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
1d480 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1d490 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
1d4a0 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
1d4b0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1d4c0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
1d4d0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
1d4e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1d4f0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
1d500 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
1d510 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
1d520 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
1d530 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
1d540 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
1d550 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
1d560 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
1d570 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
1d580 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
1d590 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
1d5a0 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
1d5b0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
1d5c0 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
1d5d0 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
1d5e0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
1d5f0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
1d600 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
1d610 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
1d620 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
1d630 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
1d640 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
1d650 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
1d660 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1d670 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
1d680 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
1d690 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
1d6a0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
1d6b0 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
1d6c0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
1d6d0 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
1d6e0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
1d6f0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54   buffer P..** ^T
1d700 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63  he P parameter c
1d710 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  an be a NULL poi
1d720 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  nter..**.** ^If 
1d730 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73  this routine has
1d740 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f   not been previo
1d750 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69  usly called or i
1d760 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a  f the previous.*
1d770 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73  * call had N les
1d780 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20  s than one or a 
1d790 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
1d7a0 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e   P, then the PRN
1d7b0 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75  G is.** seeded u
1d7c0 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
1d7d0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68  obtained from th
1d7e0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
1d7f0 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64  thod of.** the d
1d800 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1d810 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
1d820 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73  ^If the previous
1d830 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1d840 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f  utine had an N o
1d850 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20  f 1 or more and 
1d860 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20  a.** non-NULL P 
1d870 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d  then the pseudo-
1d880 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1d890 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1d8a0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1d8b0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1d8c0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1d8d0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1d8e0 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
1d8f0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
1d900 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
1d910 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d920 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
1d930 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
1d940 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1d950 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
1d960 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
1d970 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
1d980 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1d990 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1d9a0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
1d9b0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
1d9c0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
1d9d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d9e0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1d9f0 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
1da00 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
1da10 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
1da20 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1da30 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
1da40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1da50 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
1da60 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1da70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1da80 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
1da90 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
1daa0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
1dab0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
1dac0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
1dad0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
1dae0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
1daf0 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
1db00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1db10 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1db20 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
1db30 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
1db40 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
1db50 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1db60 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
1db70 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1db80 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
1db90 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
1dba0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
1dbb0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
1dbc0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
1dbd0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
1dbe0 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
1dbf0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
1dc00 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
1dc10 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
1dc20 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
1dc30 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
1dc40 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
1dc50 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
1dc60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1dc70 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1dc80 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1dc90 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
1dca0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
1dcb0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
1dcc0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
1dcd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1dce0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1dcf0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1dd00 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
1dd10 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1dd20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1dd30 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1dd40 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
1dd50 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1dd60 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
1dd70 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
1dd80 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
1dd90 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
1dda0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1ddb0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
1ddc0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1ddd0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1dde0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1ddf0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1de00 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1de10 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1de20 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1de30 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
1de40 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
1de50 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
1de60 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1de70 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1de80 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1de90 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1dea0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
1deb0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1dec0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1ded0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
1dee0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1def0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
1df00 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1df10 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
1df20 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
1df30 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1df40 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
1df50 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
1df60 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
1df70 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1df80 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
1df90 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1dfa0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
1dfb0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1dfc0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
1dfd0 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
1dfe0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1dff0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1e000 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1e010 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1e020 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
1e030 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
1e040 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1e050 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1e060 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1e070 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
1e080 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
1e090 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
1e0a0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
1e0b0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
1e0c0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1e0d0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
1e0e0 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
1e0f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
1e100 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
1e110 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
1e120 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
1e130 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
1e140 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
1e150 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
1e160 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
1e170 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
1e180 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1e190 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1e1a0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
1e1b0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1e1c0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
1e1d0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
1e1e0 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
1e1f0 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
1e200 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
1e210 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
1e220 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
1e230 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
1e240 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
1e250 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
1e260 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
1e270 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1e280 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
1e290 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1e2a0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
1e2b0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
1e2c0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
1e2d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1e2e0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
1e2f0 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
1e300 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
1e310 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
1e320 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
1e330 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
1e340 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
1e350 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
1e360 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
1e370 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
1e380 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
1e390 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
1e3a0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
1e3b0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
1e3c0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
1e3d0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
1e3e0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
1e3f0 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
1e400 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
1e410 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
1e420 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
1e430 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
1e440 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
1e450 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
1e460 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
1e470 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
1e480 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
1e490 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
1e4a0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1e4b0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
1e4c0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
1e4d0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
1e4e0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1e4f0 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
1e500 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
1e510 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
1e520 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
1e530 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
1e540 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
1e550 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
1e560 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
1e570 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
1e580 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
1e590 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
1e5a0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1e5b0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
1e5c0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
1e5d0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
1e5e0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
1e5f0 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
1e600 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
1e610 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
1e620 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
1e630 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
1e640 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
1e650 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
1e660 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
1e670 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
1e680 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
1e690 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
1e6a0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
1e6b0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
1e6c0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
1e6d0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1e6e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
1e6f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e700 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1e710 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1e720 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1e730 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e740 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1e750 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e760 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
1e770 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1e780 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1e790 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1e7a0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1e7b0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1e7c0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1e7d0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1e7e0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1e7f0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
1e800 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
1e810 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
1e820 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
1e830 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
1e840 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
1e850 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
1e860 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
1e870 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
1e880 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
1e890 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
1e8a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
1e8b0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
1e8c0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
1e8d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e8e0 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
1e8f0 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
1e900 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e910 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
1e920 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
1e930 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1e940 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
1e950 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
1e960 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1e970 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
1e980 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
1e990 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
1e9a0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
1e9b0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
1e9c0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
1e9d0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
1e9e0 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
1e9f0 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
1ea00 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
1ea10 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
1ea20 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
1ea30 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
1ea40 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
1ea50 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
1ea60 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
1ea70 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
1ea80 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
1ea90 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
1eaa0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1eab0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1eac0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
1ead0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
1eae0 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
1eaf0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1eb00 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
1eb10 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1eb20 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1eb30 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1eb40 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1eb50 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1eb60 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1eb70 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1eb80 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1eb90 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1eba0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1ebb0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1ebc0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1ebd0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1ebe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1ebf0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1ec00 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1ec10 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1ec20 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1ec30 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
1ec40 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
1ec50 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
1ec60 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20   as a [conflict 
1ec70 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d  resolution mode]
1ec80 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f  .** returned fro
1ec90 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
1eca0 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
1ecb0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
1ecc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ecd0 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
1ece0 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
1ecf0 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
1ed00 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
1ed10 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
1ed20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
1ed30 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
1ed40 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
1ed50 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
1ed60 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1ed70 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
1ed80 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1ed90 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1eda0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
1edb0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
1edc0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
1edd0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1ede0 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
1edf0 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
1ee00 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
1ee10 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1ee20 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1ee30 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1ee40 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
1ee50 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
1ee60 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
1ee70 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
1ee80 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
1ee90 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
1eea0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
1eeb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1eec0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
1eed0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
1eee0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
1eef0 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
1ef00 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
1ef10 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
1ef20 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
1ef30 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
1ef40 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
1ef50 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
1ef60 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
1ef70 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
1ef80 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
1ef90 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
1efa0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
1efb0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1efc0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
1efd0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
1efe0 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
1eff0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1f000 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1f010 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
1f020 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
1f030 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
1f040 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
1f050 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1f060 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1f070 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1f080 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1f090 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1f0a0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1f0b0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1f0c0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1f0d0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1f0e0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1f0f0 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1f100 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1f110 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
1f120 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f130 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f140 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
1f150 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
1f160 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
1f170 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1f180 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
1f190 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
1f1a0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1f1b0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f1c0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f1d0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1f1e0 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
1f1f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f200 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f210 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f220 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
1f230 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1f240 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1f250 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f260 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1f270 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
1f280 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f290 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f2a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f2b0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1f2c0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
1f2d0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1f2e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f2f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f300 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1f310 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
1f320 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1f330 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f340 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f350 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
1f360 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
1f370 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1f380 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f390 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f3a0 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
1f3b0 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
1f3c0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1f3d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f3e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f3f0 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
1f400 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
1f410 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f420 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f430 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f440 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
1f450 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
1f460 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1f470 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f480 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f490 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
1f4a0 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
1f4b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1f4c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f4d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f4e0 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
1f4f0 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
1f500 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1f510 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f520 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f530 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
1f540 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
1f550 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f560 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f570 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f580 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
1f590 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
1f5a0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1f5b0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f5c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f5d0 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
1f5e0 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
1f5f0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1f600 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f610 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f620 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1f630 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
1f640 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1f650 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1f660 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f670 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
1f680 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
1f690 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1f6a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f6b0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
1f6c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1f6d0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1f6e0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f6f0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f700 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
1f710 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
1f720 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
1f730 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
1f740 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
1f750 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
1f760 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
1f770 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f780 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1f790 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f7a0 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
1f7b0 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
1f7c0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1f7d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f7e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f7f0 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
1f800 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
1f810 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1f820 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f830 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f840 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
1f850 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
1f860 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f870 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1f880 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f890 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
1f8a0 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
1f8b0 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
1f8c0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f8d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f8e0 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
1f8f0 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
1f900 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1f910 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f920 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f930 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
1f940 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
1f950 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
1f960 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f970 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f980 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
1f990 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
1f9a0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
1f9b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f9c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f9d0 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
1f9e0 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
1f9f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1fa00 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fa10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1fa20 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
1fa30 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
1fa40 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1fa50 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1fa60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1fa70 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
1fa80 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
1fa90 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1faa0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1fab0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
1fac0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
1fad0 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
1fae0 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
1faf0 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
1fb00 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
1fb10 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
1fb20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
1fb30 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
1fb40 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
1fb50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
1fb60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1fb70 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
1fb80 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
1fb90 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49  e SQLITE_RECURSI
1fba0 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33  VE            33
1fbb0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1fbc0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1fbd0 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20        */../*.** 
1fbe0 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1fbf0 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1fc00 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1fc10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1fc20 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1fc30 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1fc40 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1fc50 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1fc60 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1fc70 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1fc80 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1fc90 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1fca0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1fcb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1fcc0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1fcd0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1fce0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1fcf0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1fd00 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1fd10 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1fd20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1fd30 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1fd40 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1fd50 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1fd60 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1fd70 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1fd80 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1fd90 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1fda0 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1fdb0 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1fdc0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1fdd0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1fde0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1fdf0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1fe00 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1fe10 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1fe20 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1fe30 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1fe40 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1fe50 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1fe60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
1fe70 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
1fe80 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
1fe90 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
1fea0 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
1feb0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
1fec0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
1fed0 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
1fee0 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
1fef0 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
1ff00 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1ff10 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1ff20 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1ff30 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1ff40 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1ff50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1ff60 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
1ff70 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1ff80 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1ff90 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1ffa0 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1ffb0 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1ffc0 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1ffd0 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1ffe0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1fff0 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
20000 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
20010 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
20020 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
20030 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
20040 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
20050 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
20060 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
20070 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
20080 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
20090 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
200a0 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
200b0 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
200c0 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
200d0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
200e0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
200f0 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
20100 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
20110 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
20120 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
20130 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
20140 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
20150 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
20160 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
20170 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
20180 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
20190 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ite..*/.void *sq
201a0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
201b0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
201c0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
201d0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
201e0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
201f0 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
20200 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
20210 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
20220 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
20230 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
20240 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
20250 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20260 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
20270 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
20280 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
20290 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
202a0 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
202b0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
202c0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
202d0 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
202e0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
202f0 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
20300 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
20310 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
20320 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
20330 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
20340 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
20350 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
20360 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
20370 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
20380 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
20390 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
203a0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
203b0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
203c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
203d0 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
203e0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
203f0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
20400 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
20410 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
20420 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
20430 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d   is the approxim
20440 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  ate number of .*
20450 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
20460 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
20470 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
20480 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
20490 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
204a0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
204b0 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20  lback X.  ^If N 
204c0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
204d0 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
204e0 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73  ss.** handler is
204f0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
20500 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
20510 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20520 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
20530 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
20540 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
20550 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
20560 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
20570 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
20580 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
20590 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
205a0 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
205b0 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
205c0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
205d0 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
205e0 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
205f0 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
20600 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
20610 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
20620 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
20630 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
20640 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
20650 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
20660 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
20670 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
20680 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
20690 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
206a0 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
206b0 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
206c0 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
206d0 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
206e0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
206f0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
20700 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
20710 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
20720 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20730 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
20740 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
20750 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
20760 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
20770 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
20780 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
20790 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
207a0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
207b0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
207c0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
207d0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
207e0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
207f0 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
20800 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
20810 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
20820 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
20830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20840 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
20850 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
20860 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
20870 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
20880 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
20890 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
208a0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
208b0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
208c0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
208d0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
208e0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
208f0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
20900 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
20910 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
20920 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
20930 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
20940 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
20950 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
20960 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
20970 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
20980 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
20990 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
209a0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
209b0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
209c0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
209d0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
209e0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
209f0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
20a00 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
20a10 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
20a20 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
20a30 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
20a40 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
20a50 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
20a60 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
20a70 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
20a80 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20a90 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
20aa0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
20ab0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
20ac0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
20ad0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
20ae0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
20af0 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
20b00 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
20b10 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
20b20 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
20b30 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
20b40 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
20b50 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
20b60 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
20b70 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
20b80 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
20b90 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
20ba0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
20bb0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
20bc0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
20bd0 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54  oding will be UT
20be0 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65  F-8 for database
20bf0 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
20c00 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
20c10 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
20c20 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65  n_v2().  ^The de
20c30 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
20c40 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20  or databases.** 
20c50 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71  created using sq
20c60 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77  lite3_open16() w
20c70 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e  ill be UTF-16 in
20c80 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
20c90 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68   order..**.** Wh
20ca0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
20cb0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
20cc0 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
20cd0 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
20ce0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
20cf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
20d00 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
20d10 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
20d20 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
20d30 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
20d40 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
20d50 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
20d60 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
20d70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20d80 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
20d90 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
20da0 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
20db0 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
20dc0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
20dd0 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
20de0 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
20df0 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
20e00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20e10 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
20e20 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
20e30 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
20e40 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
20e50 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
20e60 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
20e70 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
20e80 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
20e90 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
20ea0 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
20eb0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
20ec0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
20ed0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
20ee0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
20ef0 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
20f00 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
20f10 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
20f20 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
20f30 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
20f40 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
20f50 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
20f60 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
20f70 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
20f80 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
20f90 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
20fa0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
20fb0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
20fc0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
20fd0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
20fe0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
20ff0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
21000 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
21010 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
21020 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
21030 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
21040 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
21050 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
21060 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
21070 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
21080 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
21090 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
210a0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
210b0 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
210c0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
210d0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
210e0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
210f0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
21100 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
21110 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
21120 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
21130 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
21140 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
21150 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
21160 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
21170 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
21180 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
21190 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
211a0 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
211b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
211c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
211d0 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
211e0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
211f0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
21200 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
21210 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
21220 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
21230 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
21240 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
21250 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
21260 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
21270 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
21280 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
21290 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
212a0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
212b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
212c0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
212d0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
212e0 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
212f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21300 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
21310 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
21320 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
21330 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
21340 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
21350 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
21360 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
21370 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
21380 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
21390 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
213a0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
213b0 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
213c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
213d0 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
213e0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
213f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
21400 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
21410 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
21420 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
21430 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
21440 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
21450 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
21460 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
21470 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
21480 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21490 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
214a0 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
214b0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
214c0 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
214d0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
214e0 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
214f0 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
21500 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
21510 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
21520 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
21530 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
21540 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
21550 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
21560 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
21570 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
21580 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
21590 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
215a0 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
215b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
215c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
215d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
215e0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
215f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
21600 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
21610 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
21620 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
21630 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
21640 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
21650 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
21660 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
21670 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
21680 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
21690 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
216a0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
216b0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
216c0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
216d0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
216e0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
216f0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
21700 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
21710 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
21720 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
21730 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
21740 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
21750 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
21760 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
21770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21780 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
21790 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
217a0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
217b0 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
217c0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
217d0 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
217e0 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
217f0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
21800 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
21810 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
21820 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
21830 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
21840 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
21850 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
21860 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
21870 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
21880 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
21890 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
218a0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
218b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
218c0 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
218d0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
218e0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
218f0 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
21900 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
21910 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
21920 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
21930 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
21940 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
21950 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
21960 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21970 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
21980 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
21990 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
219a0 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
219b0 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
219c0 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
219d0 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
219e0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
219f0 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
21a00 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
21a10 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
21a20 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
21a30 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
21a40 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
21a50 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
21a60 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
21a70 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
21a80 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
21a90 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
21aa0 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
21ab0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
21ac0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
21ad0 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
21ae0 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
21af0 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
21b00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
21b10 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
21b20 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
21b30 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
21b40 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
21b50 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
21b60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
21b70 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
21b80 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
21b90 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
21ba0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
21bb0 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
21bc0 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
21bd0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
21be0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
21bf0 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
21c00 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
21c10 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
21c20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
21c30 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
21c40 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
21c50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
21c60 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
21c70 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
21c80 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
21c90 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
21ca0 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
21cb0 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
21cc0 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
21cd0 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
21ce0 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
21cf0 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
21d00 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
21d10 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
21d20 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
21d30 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
21d40 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
21d50 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
21d60 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
21d70 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
21d80 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
21d90 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
21da0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
21db0 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
21dc0 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
21dd0 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
21de0 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
21df0 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
21e00 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
21e10 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
21e20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
21e30 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
21e40 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
21e50 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
21e60 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
21e70 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
21e80 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
21e90 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
21ea0 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
21eb0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
21ec0 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
21ed0 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
21ee0 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
21ef0 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
21f00 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
21f10 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
21f20 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
21f30 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
21f40 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
21f50 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
21f60 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
21f70 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
21f80 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
21f90 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
21fa0 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
21fb0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
21fc0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
21fd0 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
21fe0 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
21ff0 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
22000 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
22010 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
22020 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
22030 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
22040 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
22050 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
22060 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
22070 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
22080 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
22090 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
220a0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
220b0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
220c0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
220d0 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
220e0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
220f0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
22100 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
22110 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
22120 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
22130 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
22140 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
22150 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
22160 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
22170 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
22180 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
22190 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
221a0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
221b0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
221c0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
221d0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
221e0 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
221f0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
22200 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
22210 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
22220 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
22230 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
22240 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
22250 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
22260 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
22270 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
22280 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
22290 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
222a0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
222b0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
222c0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
222d0 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
222e0 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
222f0 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
22300 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
22310 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
22320 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
22330 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
22340 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
22350 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
22360 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
22370 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
22380 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
22390 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
223a0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
223b0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
223c0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
223d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
223e0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
223f0 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
22400 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
22410 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
22420 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
22430 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
22440 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
22450 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
22460 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
22470 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
22480 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
22490 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
224a0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
224b0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
224c0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
224d0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
224e0 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
224f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
22500 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
22510 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
22520 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
22530 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
22540 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
22550 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
22560 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
22570 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
22580 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
22590 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
225a0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
225b0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
225c0 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
225d0 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
225e0 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
225f0 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
22600 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
22610 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
22620 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
22630 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
22640 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
22650 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
22660 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
22670 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
22680 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
22690 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
226a0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
226b0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
226c0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
226d0 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
226e0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
226f0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
22700 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
22710 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
22720 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
22730 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
22740 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
22750 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
22760 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
22770 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
22780 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
22790 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
227a0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
227b0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
227c0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
227d0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
227e0 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
227f0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
22800 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
22810 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
22820 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
22830 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
22840 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
22850 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
22860 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
22870 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
22880 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
22890 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
228a0 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
228b0 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
228c0 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
228d0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
228e0 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
228f0 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
22900 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
22910 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
22920 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
22930 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
22940 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22950 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
22960 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
22970 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
22980 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
22990 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
229a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
229b0 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
229c0 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
229d0 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
229e0 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
229f0 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
22a00 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
22a10 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
22a20 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
22a30 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
22a40 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
22a50 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
22a60 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
22a70 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
22a80 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
22a90 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
22aa0 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
22ab0 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
22ac0 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
22ad0 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
22ae0 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
22af0 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
22b00 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
22b10 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
22b20 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
22b30 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
22b40 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
22b50 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
22b60 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
22b70 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
22b80 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
22b90 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
22ba0 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
22bb0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
22bc0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
22bd0 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
22be0 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
22bf0 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
22c00 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
22c10 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
22c20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
22c30 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
22c40 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
22c50 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
22c60 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
22c70 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
22c80 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
22c90 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
22ca0 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
22cb0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
22cc0 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
22cd0 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
22ce0 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
22cf0 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
22d00 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
22d10 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
22d20 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
22d30 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
22d40 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
22d50 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
22d60 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
22d70 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
22d80 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
22d90 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
22da0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
22db0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
22dc0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
22dd0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
22de0 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
22df0 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
22e00 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
22e10 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
22e20 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
22e30 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
22e40 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
22e50 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
22e60 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
22e70 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
22e80 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
22e90 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
22ea0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
22eb0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
22ec0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
22ed0 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
22ee0 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
22ef0 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
22f00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22f10 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
22f20 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
22f30 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
22f40 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
22f50 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
22f60 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
22f70 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
22f80 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
22f90 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
22fa0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
22fb0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
22fc0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
22fd0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
22fe0 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
22ff0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
23000 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
23010 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23020 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
23030 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
23040 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23050 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
23060 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
23070 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
23080 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
23090 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
230a0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
230b0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
230c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
230d0 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
230e0 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
230f0 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
23100 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
23110 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
23120 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
23130 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
23140 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
23150 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
23160 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
23170 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
23180 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
23190 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
231a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
231b0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
231c0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
231d0 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
231e0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
231f0 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
23200 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
23210 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
23220 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
23230 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
23240 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
23250 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
23260 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
23270 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
23280 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
23290 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
232a0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
232b0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
232c0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
232d0 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
232e0 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
232f0 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
23300 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
23310 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
23320 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
23330 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
23340 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
23350 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
23360 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
23370 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
23380 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
23390 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
233a0 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
233b0 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
233c0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
233d0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
233e0 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
233f0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
23400 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
23410 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
23420 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
23430 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
23440 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
23450 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
23460 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
23470 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
23480 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
23490 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
234a0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
234b0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
234c0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
234d0 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
234e0 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
234f0 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
23500 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
23510 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
23520 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
23530 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
23540 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
23550 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
23560 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
23570 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
23580 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
23590 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
235a0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
235b0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
235c0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
235d0 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
235e0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
235f0 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
23600 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
23610 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
23620 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
23630 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
23640 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
23650 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
23660 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
23670 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
23680 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
23690 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
236a0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
236b0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
236c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
236d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
236e0 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
236f0 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
23700 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
23710 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
23720 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
23730 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
23740 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
23750 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
23760 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
23770 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
23780 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
23790 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
237a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
237b0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
237c0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
237d0 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
237e0 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
237f0 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
23800 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
23810 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
23820 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
23830 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
23840 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
23850 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
23860 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
23870 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
23880 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
23890 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
238a0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
238b0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
238c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
238d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
238e0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
238f0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
23900 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
23910 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
23920 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
23930 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
23940 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
23950 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
23960 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
23970 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
23980 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
23990 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
239a0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
239b0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
239c0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
239d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
239e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
239f0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
23a00 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
23a10 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
23a20 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
23a30 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
23a40 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
23a50 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
23a60 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
23a70 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
23a80 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
23a90 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
23aa0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
23ab0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
23ac0 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
23ad0 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
23ae0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
23af0 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
23b00 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
23b10 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
23b20 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
23b30 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
23b40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
23b50 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
23b60 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
23b70 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
23b80 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
23b90 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
23ba0 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
23bb0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
23bc0 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
23bd0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
23be0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
23bf0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
23c00 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
23c10 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
23c20 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
23c30 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
23c40 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
23c50 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
23c60 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
23c70 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
23c80 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
23c90 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
23ca0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
23cb0 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
23cc0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
23cd0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
23ce0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
23cf0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
23d00 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
23d10 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
23d20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
23d30 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
23d40 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
23d50 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
23d60 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
23d70 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
23d80 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
23d90 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
23da0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
23db0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
23dc0 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
23dd0 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
23de0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
23df0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
23e00 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
23e10 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
23e20 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
23e30 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
23e40 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
23e50 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
23e60 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
23e70 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
23e80 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
23e90 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
23ea0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
23eb0 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
23ec0 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
23ed0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
23ee0 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
23ef0 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
23f00 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
23f10 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
23f20 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
23f30 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
23f40 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
23f50 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
23f60 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
23f70 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
23f80 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
23f90 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
23fa0 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
23fb0 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
23fc0 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
23fd0 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
23fe0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
23ff0 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
24000 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
24010 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
24020 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
24030 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
24040 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
24050 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
24060 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
24070 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
24080 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
24090 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
240a0 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
240b0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
240c0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
240d0 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
240e0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
240f0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
24100 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
24110 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
24120 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
24130 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
24140 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
24150 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
24160 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
24170 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
24180 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
24190 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
241a0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
241b0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
241c0 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
241d0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
241e0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
241f0 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
24200 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
24210 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
24220 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
24230 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
24240 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
24250 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
24260 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
24270 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
24280 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
24290 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
242a0 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
242b0 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e  esirable..*/.con
242c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
242d0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
242e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
242f0 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
24300 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
24310 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24320 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
24330 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
24340 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
24350 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
24360 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
24370 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
24380 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
24390 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
243a0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
243b0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
243c0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
243d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
243e0 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72  _errcode() inter
243f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
24400 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
24410 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
24420 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
24430 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
24440 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
24450 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
24460 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  l.** associated 
24470 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
24480 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66   connection]. If
24490 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
244a0 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20  l failed.** but 
244b0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
244c0 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
244d0 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
244e0 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  alue from.** sql
244f0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
24500 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54  s undefined.  ^T
24510 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
24520 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
24530 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
24540 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
24550 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
24560 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
24570 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
24580 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
24590 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
245a0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
245b0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
245c0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
245d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
245e0 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
245f0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
24600 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
24610 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
24620 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
24630 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
24640 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
24650 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
24660 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
24670 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
24680 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
24690 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
246a0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
246b0 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
246c0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
246d0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
246e0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
246f0 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
24700 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
24710 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
24720 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
24730 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
24740 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
24750 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
24760 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
24770 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24780 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
24790 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
247a0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
247b0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
247c0 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
247d0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
247e0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
247f0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
24800 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
24810 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
24820 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
24830 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
24840 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
24850 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
24860 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
24870 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
24880 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
24890 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
248a0 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
248b0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
248c0 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
248d0 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
248e0 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
248f0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
24900 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
24910 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
24920 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
24930 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
24940 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
24950 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
24960 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
24970 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
24980 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
24990 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
249a0 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
249b0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
249c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
249d0 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
249e0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
249f0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
24a00 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
24a10 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
24a20 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
24a30 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
24a40 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
24a50 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
24a60 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
24a70 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
24a80 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
24a90 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
24aa0 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
24ab0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
24ac0 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
24ad0 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
24ae0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
24af0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
24b00 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
24b10 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
24b20 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
24b30 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
24b40 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
24b50 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
24b60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24b70 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
24b80 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
24b90 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
24ba0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
24bb0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
24bc0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
24bd0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
24be0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
24bf0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
24c00 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
24c10 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
24c20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24c30 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
24c40 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
24c50 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
24c60 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
24c70 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
24c80 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
24c90 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
24ca0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
24cb0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
24cc0 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
24cd0 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
24ce0 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
24cf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
24d00 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
24d10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
24d20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
24d30 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
24d40 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
24d50 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
24d60 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
24d70 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
24d80 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
24d90 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
24da0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
24db0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
24dc0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
24dd0 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
24de0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
24df0 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
24e00 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
24e10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
24e20 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
24e30 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
24e40 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
24e50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
24e60 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
24e70 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
24e80 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
24e90 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
24ea0 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
24eb0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
24ec0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
24ed0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
24ee0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
24ef0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
24f00 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
24f10 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
24f20 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
24f30 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
24f40 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
24f50 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
24f60 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
24f70 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
24f80 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24f90 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
24fa0 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
24fb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
24fc0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
24fd0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
24fe0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
24ff0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
25000 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
25010 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
25020 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
25030 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
25040 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
25050 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
25060 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25070 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
25080 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
25090 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
250a0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
250b0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
250c0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
250d0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
250e0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
250f0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
25100 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
25110 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
25120 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
25130 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
25140 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
25150 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
25160 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
25170 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
25180 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
25190 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
251a0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
251b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
251c0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
251d0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
251e0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
251f0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
25200 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
25210 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
25220 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
25230 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
25240 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
25250 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
25260 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
25270 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
25280 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
25290 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
252a0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
252b0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
252c0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
252d0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
252e0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
252f0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
25300 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
25310 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
25320 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
25330 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
25340 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
25350 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25360 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
25370 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
25380 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
25390 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
253a0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
253b0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
253c0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
253d0 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
253e0 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
253f0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
25400 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
25410 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
25420 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
25430 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
25440 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
25450 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
25460 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
25470 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
25480 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
25490 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
254a0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
254b0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
254c0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
254d0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
254e0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
254f0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
25500 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
25510 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
25520 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
25530 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
25540 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
25550 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
25560 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
25570 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
25580 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
25590 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
255a0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
255b0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
255c0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
255d0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
255e0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
255f0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
25600 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
25610 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
25620 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
25630 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
25640 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
25650 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
25660 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
25670 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
25680 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
25690 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
256a0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
256b0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
256c0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
256d0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
256e0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
256f0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
25700 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
25710 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
25720 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
25730 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
25740 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
25750 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
25760 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
25770 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
25780 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
25790 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
257a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
257b0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
257c0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
257d0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
257e0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
257f0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
25800 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
25810 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
25820 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
25830 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
25840 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
25850 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
25860 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
25870 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
25880 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
25890 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
258a0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
258b0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
258c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
258d0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
258e0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
258f0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
25900 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
25910 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
25920 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25930 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
25940 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25950 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
25960 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
25970 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
25980 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
25990 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
259a0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
259b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
259c0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
259d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
259e0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
259f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
25a00 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
25a10 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25a20 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
25a30 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25a40 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
25a50 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25a60 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
25a70 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
25a80 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
25a90 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
25aa0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
25ab0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
25ac0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
25ad0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
25ae0 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
25af0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
25b00 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
25b10 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25b20 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
25b30 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25b40 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
25b50 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25b60 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
25b70 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
25b80 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
25b90 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
25ba0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
25bb0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
25bc0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
25bd0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
25be0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25bf0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
25c00 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
25c10 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
25c20 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
25c30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25c40 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
25c50 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25c60 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
25c70 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25c80 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
25c90 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
25ca0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
25cb0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
25cc0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
25cd0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
25ce0 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
25cf0 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
25d00 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
25d10 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
25d20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
25d30 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
25d40 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
25d50 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25d60 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
25d70 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25d80 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
25d90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25da0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
25db0 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
25dc0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
25dd0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25de0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
25df0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
25e00 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
25e10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25e20 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25e30 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
25e40 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
25e50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
25e60 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
25e70 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
25e80 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
25e90 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
25ea0 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
25eb0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25ec0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
25ed0 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
25ee0 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
25ef0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
25f00 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
25f10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25f20 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
25f30 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
25f40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
25f50 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
25f60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25f70 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
25f80 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
25f90 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
25fa0 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
25fb0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25fc0 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
25fd0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25fe0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
25ff0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26000 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
26010 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
26020 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
26030 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26040 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
26050 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EADS]] ^(<dt>SQL
26060 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
26070 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a  _THREADS</dt>.**
26080 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26090 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c   number of auxil
260a0 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65  iary worker thre
260b0 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c  ads that a singl
260c0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
260d0 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74  tatement] may st
260e0 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  art.</dd>)^.** <
260f0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
26100 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
26110 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
26120 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
26130 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
26140 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
26150 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
26160 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
26170 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
26180 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
26190 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
261a0 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
261b0 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
261c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
261d0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
261e0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
261f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26200 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
26210 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
26220 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26230 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
26240 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
26250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26260 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
26270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
26280 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26290 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
262a0 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
262b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
262c0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
262d0 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
262e0 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
262f0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
26300 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
26310 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
26320 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
26330 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20  HREADS          
26340 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   11../*.** CAPI3
26350 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
26360 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
26370 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
26380 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
26390 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
263a0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
263b0 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
263c0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
263d0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
263e0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
263f0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
26400 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
26410 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
26420 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
26430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26440 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
26450 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
26460 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
26470 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
26480 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
26490 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
264a0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
264b0 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
264c0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
264d0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
264e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
264f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
26500 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
26510 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
26520 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
26530 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
26540 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
26550 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
26560 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
26570 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
26580 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
26590 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
265a0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
265b0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
265c0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
265d0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
265e0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
265f0 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
26600 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
26610 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
26620 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
26630 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
26640 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
26650 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
26660 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
26670 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
26680 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
26690 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
266a0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
266b0 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
266c0 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
266d0 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
266e0 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
266f0 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
26700 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
26710 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
26720 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
26730 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
26740 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
26750 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
26760 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
26770 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
26780 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
26790 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
267a0 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
267b0 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
267c0 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
267d0 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
267e0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
267f0 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
26800 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
26810 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
26820 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
26830 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53   as this saves S
26840 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e  QLite from havin
26850 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63  g to.** make a c
26860 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74  opy of the input
26870 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
26880 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
26890 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
268a0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
268b0 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
268c0 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
268d0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
268e0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
268f0 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
26900 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
26910 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
26920 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
26930 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
26940 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
26950 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
26960 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
26970 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
26980 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
26990 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
269a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
269b0 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
269c0 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
269d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
269e0 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
269f0 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
26a00 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
26a10 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
26a20 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
26a30 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
26a40 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
26a50 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
26a60 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
26a70 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
26a80 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
26a90 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
26aa0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
26ab0 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
26ac0 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
26ad0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
26ae0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
26af0 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
26b00 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
26b10 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
26b20 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
26b30 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
26b40 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
26b50 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
26b60 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
26b70 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
26b80 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
26b90 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
26ba0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
26bb0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
26bc0 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
26bd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26be0 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
26bf0 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
26c00 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
26c10 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
26c20 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
26c30 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
26c40 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
26c50 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
26c60 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
26c70 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
26c80 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
26c90 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
26ca0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26cb0 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
26cc0 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
26cd0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
26ce0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
26cf0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
26d00 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
26d10 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
26d20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
26d30 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
26d40 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
26d50 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
26d60 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
26d70 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
26d80 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
26d90 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
26da0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
26db0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
26dc0 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
26dd0 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
26de0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
26df0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
26e00 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
26e10 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
26e20 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
26e30 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
26e40 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
26e50 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
26e60 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
26e70 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
26e80 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
26e90 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
26ea0 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
26eb0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
26ec0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
26ed0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
26ee0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
26ef0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
26f00 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
26f10 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
26f20 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
26f30 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
26f40 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
26f50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
26f60 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
26f70 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
26f80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
26f90 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
26fa0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
26fb0 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
26fc0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
26fd0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
26fe0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
26ff0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
27000 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
27010 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
27020 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
27030 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
27040 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
27050 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
27060 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
27070 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
27080 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
27090 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
270a0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
270b0 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
270c0 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
270d0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
270e0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
270f0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
27100 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
27110 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
27120 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
27130 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
27140 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
27150 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
27160 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
27170 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
27180 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
27190 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
271a0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
271b0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
271c0 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
271d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
271e0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
271f0 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
27200 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
27210 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
27220 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
27230 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
27240 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
27250 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
27260 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
27270 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
27280 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
27290 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
272a0 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
272b0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
272c0 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
272d0 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
272e0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
272f0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
27300 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
27310 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
27320 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
27330 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
27340 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
27350 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
27360 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
27370 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
27380 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
27390 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
273a0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
273b0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
273c0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
273d0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
273e0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
273f0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
27400 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
27410 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
27420 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
27430 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
27440 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
27450 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
27460 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
27470 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
27480 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27490 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
274a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
274b0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
274c0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
274d0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
274e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
274f0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
27500 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
27510 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
27520 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
27530 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
27540 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
27550 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
27560 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
27570 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
27580 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
27590 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
275a0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
275b0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
275c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
275d0 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
275e0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
275f0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
27600 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
27610 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
27620 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
27630 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
27640 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
27650 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
27660 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
27670 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
27680 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
27690 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
276a0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
276b0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
276c0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
276d0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
276e0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
276f0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
27700 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
27710 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
27720 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
27730 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
27740 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
27750 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
27760 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
27770 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
27780 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
27790 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
277a0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
277b0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
277c0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
277d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
277e0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
277f0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
27800 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
27810 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
27820 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
27830 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
27840 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
27850 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27860 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
27870 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
27880 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
27890 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
278a0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
278b0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
278c0 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
278d0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
278e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
278f0 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
27900 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
27910 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
27920 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
27930 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
27940 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27950 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
27960 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
27970 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
27980 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
27990 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
279a0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
279b0 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
279c0 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a  The Database.**.
279d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
279e0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
279f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
27a00 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
27a10 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
27a20 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
27a30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
27a40 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
27a50 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
27a60 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
27a70 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
27a80 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
27a90 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
27aa0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
27ab0 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
27ac0 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
27ad0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
27ae0 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
27af0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
27b00 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
27b10 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
27b20 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
27b30 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
27b40 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
27b50 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
27b60 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
27b70 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
27b80 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
27b90 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
27ba0 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
27bb0 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
27bc0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
27bd0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
27be0 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
27bf0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
27c00 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
27c10 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
27c20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
27c30 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
27c40 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
27c50 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
27c60 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
27c70 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
27c80 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
27c90 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
27ca0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
27cb0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
27cc0 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
27cd0 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
27ce0 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
27cf0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
27d00 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
27d10 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
27d20 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
27d30 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
27d40 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
27d50 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
27d60 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
27d70 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
27d80 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
27d90 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
27da0 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
27db0 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
27dc0 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
27dd0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
27de0 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
27df0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
27e00 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
27e10 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
27e20 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
27e30 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
27e40 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
27e50 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
27e60 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
27e70 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
27e80 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
27e90 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
27ea0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
27eb0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
27ec0 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
27ed0 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73  n disk..*/.int s
27ee0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
27ef0 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
27f00 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
27f10 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
27f20 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
27f30 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
27f40 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a  s Been Reset.**.
27f50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27f60 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
27f70 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
27f80 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
27f90 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
27fa0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
27fb0 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
27fc0 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
27fd0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
27fe0 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
27ff0 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f  as not run to co
28000 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20  mpletion and/or 
28010 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e  has not .** been
28020 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
28030 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
28040 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
28050 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
28060 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28070 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
28080 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
28090 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
280a0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
280b0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
280c0 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
280d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
280e0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
280f0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
28100 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
28110 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
28120 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
28130 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
28140 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
28150 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
28160 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
28170 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
28180 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28190 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
281a0 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
281b0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
281c0 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
281d0 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
281e0 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
281f0 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
28200 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
28210 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
28220 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
28230 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
28240 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
28250 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
28260 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
28270 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
28280 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
28290 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
282a0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
282b0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
282c0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
282d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
282e0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
282f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
28300 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
28310 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
28320 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
28330 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
28340 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
28350 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
28360 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
28370 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
28380 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
28390 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
283a0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
283b0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
283c0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
283d0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
283e0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
283f0 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
28400 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
28410 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
28420 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
28430 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
28440 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
28450 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
28460 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
28470 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
28480 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28490 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
284a0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
284b0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
284c0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
284d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
284e0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
284f0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
28500 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
28510 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
28520 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
28530 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
28540 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
28550 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28560 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
28570 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
28580 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
28590 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
285a0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
285b0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
285c0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
285d0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
285e0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
285f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
28600 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
28610 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
28620 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
28630 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
28640 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
28650 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
28660 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
28670 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
28680 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
28690 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
286a0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
286b0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
286c0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
286d0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
286e0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
286f0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
28700 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
28710 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
28720 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
28730 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
28740 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
28750 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
28760 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
28770 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28780 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
28790 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
287a0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
287b0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
287c0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
287d0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
287e0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
287f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
28800 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
28810 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
28820 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
28830 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
28840 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28850 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
28860 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
28870 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
28880 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
28890 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
288a0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
288b0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
288c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
288d0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
288e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
288f0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
28900 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
28910 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28920 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
28930 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
28940 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
28950 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
28960 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
28970 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
28980 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
28990 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
289a0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
289b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
289c0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
289d0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
289e0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
289f0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
28a00 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
28a10 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
28a20 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
28a30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28a40 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
28a50 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
28a60 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
28a70 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
28a80 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
28a90 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
28aa0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
28ab0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
28ac0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
28ad0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
28ae0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
28af0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
28b00 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
28b10 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
28b20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
28b30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
28b40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
28b50 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
28b60 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
28b70 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
28b80 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
28b90 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
28ba0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
28bb0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
28bc0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
28bd0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
28be0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
28bf0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
28c00 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
28c10 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
28c20 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
28c30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
28c40 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
28c50 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
28c60 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
28c70 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
28c80 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
28c90 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
28ca0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
28cb0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
28cc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
28cd0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
28ce0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
28cf0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
28d00 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
28d10 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
28d20 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
28d30 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
28d40 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
28d50 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
28d60 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
28d70 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
28d80 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
28d90 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
28da0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
28db0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
28dc0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
28dd0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
28de0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
28df0 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
28e00 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
28e10 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
28e20 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
28e30 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
28e40 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
28e50 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
28e60 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
28e70 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
28e80 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
28e90 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
28ea0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
28eb0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
28ec0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
28ed0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
28ee0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
28ef0 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
28f00 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
28f10 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
28f20 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
28f30 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
28f40 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
28f50 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
28f60 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
28f70 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
28f80 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
28f90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
28fa0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
28fb0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
28fc0 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
28fd0 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
28fe0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
28ff0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
29000 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
29010 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29020 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
29030 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
29040 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
29050 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
29060 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
29070 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
29080 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
29090 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
290a0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
290b0 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
290c0 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
290d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
290e0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
290f0 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
29100 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
29110 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
29120 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
29130 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
29140 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
29150 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
29160 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
29170 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
29180 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
29190 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
291a0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
291b0 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
291c0 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
291d0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
291e0 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
291f0 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
29200 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
29210 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
29220 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
29230 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
29240 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
29250 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
29260 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
29270 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
29280 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
29290 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
292a0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
292b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
292c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
292d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
292e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
292f0 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
29300 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
29310 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
29320 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
29330 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
29340 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
29350 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
29360 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
29370 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
29380 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
29390 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
293a0 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
293b0 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
293c0 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
293d0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
293e0 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
293f0 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
29400 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
29410 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
29420 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
29430 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
29440 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
29450 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
29460 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
29470 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
29480 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
29490 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
294a0 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
294b0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
294c0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
294d0 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
294e0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
294f0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
29500 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
29510 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
29520 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29530 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
29540 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
29550 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
29560 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
29570 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
29580 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
29590 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
295a0 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
295b0 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
295c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
295d0 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65  xt16() or sqlite
295e0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
295f0 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72  then.** that par
29600 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
29610 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
29620 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
29630 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
29640 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
29650 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
29660 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
29670 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
29680 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
29690 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
296a0 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
296b0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
296c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
296d0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
296e0 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
296f0 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
29700 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
29710 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
29720 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
29730 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
29740 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
29750 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
29760 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
29770 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
29780 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67   BLOB and string
29790 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61   binding interfa
297a0 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74  ces.** is a dest
297b0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
297c0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
297d0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
297e0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
297f0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
29800 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
29810 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
29820 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
29830 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
29840 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
29850 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66  ll to bind API f
29860 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ails..** ^If the
29870 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
29880 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
29890 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
298a0 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
298b0 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
298c0 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
298d0 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
298e0 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
298f0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
29900 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
29910 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
29920 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
29930 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
29940 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
29950 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
29960 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
29970 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
29980 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
29990 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
299a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
299b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
299c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
299d0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
299e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
299f0 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  4() must be one 
29a00 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  of.** [SQLITE_UT
29a10 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
29a20 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
29a30 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
29a40 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f  E_UTF16LE].** to
29a50 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63   specify the enc
29a60 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78  oding of the tex
29a70 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  t in the third p
29a80 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a  arameter.  If.**
29a90 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d   the sixth argum
29aa0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
29ab0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20  ind_text64() is 
29ac0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
29ad0 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  * allowed values
29ae0 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72   shown above, or
29af0 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63   if the text enc
29b00 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
29b10 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65  nt.** from the e
29b20 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
29b30 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70  d by the sixth p
29b40 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
29b50 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
29b60 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
29b70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29b80 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
29b90 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
29ba0 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
29bb0 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
29bc0 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
29bd0 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
29be0 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
29bf0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
29c00 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
29c10 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
29c20 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
29c30 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
29c40 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
29c50 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
29c60 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
29c70 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
29c80 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
29c90 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
29ca0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
29cb0 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
29cc0 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
29cd0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
29ce0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
29cf0 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
29d00 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
29d10 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
29d20 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
29d30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
29d40 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
29d50 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
29d60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
29d70 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
29d80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
29d90 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
29da0 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
29db0 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
29dc0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
29dd0 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
29de0 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
29df0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
29e00 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
29e10 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
29e20 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
29e30 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
29e40 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
29e50 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
29e60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29e70 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
29e80 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
29e90 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
29ea0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
29eb0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
29ec0 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
29ed0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
29ee0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
29ef0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
29f00 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
29f10 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
29f20 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
29f30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29f40 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
29f50 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
29f60 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
29f70 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
29f80 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
29f90 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
29fa0 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
29fb0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
29fc0 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66  d if the size of
29fd0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
29fe0 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d  B.** exceeds lim
29ff0 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b  its imposed by [
2a000 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2a010 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2a020 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c  GTH]) or.** [SQL
2a030 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e  ITE_MAX_LENGTH].
2a040 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
2a050 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
2a060 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2a070 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
2a080 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
2a090 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
2a0a0 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
2a0b0 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
2a0c0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2a0d0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a0e0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
2a0f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a100 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2a110 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2a120 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2a130 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2a140 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2a150 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a160 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2a170 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
2a180 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2a190 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34  ite3_bind_blob64
2a1a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a1b0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2a1c0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2a1d0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2a1e0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2a1f0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2a200 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
2a210 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2a220 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
2a230 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a240 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2a250 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
2a260 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2a270 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2a280 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2a290 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
2a2a0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2a2b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a2c0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
2a2d0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2a2e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e  e3_stmt*,int,con
2a2f0 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69  st char*,int,voi
2a300 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2a310 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2a320 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2a330 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2a340 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2a350 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2a360 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a370 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt64(sqlite3_stm
2a380 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2a390 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  har*, sqlite3_ui
2a3a0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2a3b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2a3c0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
2a3d0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
2a3e0 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69  oding);.int sqli
2a3f0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
2a400 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a410 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
2a420 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2a430 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2a440 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2a450 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
2a460 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a470 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
2a480 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
2a490 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
2a4a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
2a4b0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
2a4c0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
2a4d0 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
2a4e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2a4f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
2a500 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
2a510 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
2a520 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
2a530 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
2a540 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
2a550 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2a560 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
2a570 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2a580 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
2a590 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2a5a0 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
2a5b0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
2a5c0 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
2a5d0 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
2a5e0 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
2a5f0 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
2a600 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
2a610 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
2a620 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
2a630 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
2a640 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2a650 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
2a660 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
2a670 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
2a680 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
2a690 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
2a6a0 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
2a6b0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
2a6c0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2a6d0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2a6e0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2a6f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a700 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
2a710 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2a720 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2a730 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2a740 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a750 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2a760 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2a770 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
2a780 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
2a790 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a7a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a7b0 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
2a7c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2a7d0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
2a7e0 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
2a7f0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
2a800 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a810 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
2a820 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2a830 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
2a840 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2a850 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
2a860 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
2a870 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
2a880 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2a890 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2a8a0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
2a8b0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
2a8c0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
2a8d0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
2a8e0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
2a8f0 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
2a900 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
2a910 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
2a920 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
2a930 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
2a940 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
2a950 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
2a960 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
2a970 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
2a980 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
2a990 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
2a9a0 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
2a9b0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2a9c0 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
2a9d0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
2a9e0 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
2a9f0 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
2aa00 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
2aa10 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
2aa20 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
2aa30 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
2aa40 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2aa50 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
2aa60 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
2aa70 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
2aa80 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
2aa90 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
2aaa0 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
2aab0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
2aac0 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
2aad0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2aae0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2aaf0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2ab00 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2ab10 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2ab20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2ab30 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2ab40 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2ab50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ab60 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
2ab70 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2ab80 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ab90 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
2aba0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
2abb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
2abc0 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
2abd0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
2abe0 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
2abf0 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
2ac00 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
2ac10 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
2ac20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
2ac30 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
2ac40 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
2ac50 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
2ac60 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
2ac70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2ac80 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2ac90 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
2aca0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
2acb0 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
2acc0 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
2acd0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
2ace0 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
2acf0 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
2ad00 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
2ad10 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
2ad20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
2ad30 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
2ad40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
2ad50 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2ad60 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2ad70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2ad80 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2ad90 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2ada0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2adb0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2adc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2add0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2ade0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2adf0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2ae00 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2ae10 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2ae20 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2ae30 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2ae40 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2ae50 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2ae60 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
2ae70 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2ae80 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2ae90 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2aea0 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2aeb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2aec0 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2aed0 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2aee0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2aef0 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2af00 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2af10 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2af20 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
2af30 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
2af40 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2af50 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2af60 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2af70 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
2af80 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2af90 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
2afa0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2afb0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2afc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2afd0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2afe0 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
2aff0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2b000 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
2b010 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2b020 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
2b030 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
2b040 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
2b050 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
2b060 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2b070 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
2b080 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2b090 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2b0a0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2b0b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b0c0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2b0d0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2b0e0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2b0f0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2b100 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2b110 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2b120 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2b130 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2b140 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2b150 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2b160 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2b170 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b180 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2b190 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2b1a0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2b1b0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2b1c0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2b1d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2b1e0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2b1f0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2b200 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2b210 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2b220 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2b230 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2b240 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2b250 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2b260 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2b270 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b280 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2b290 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2b2a0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2b2b0 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2b2c0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2b2d0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2b2e0 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2b2f0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b300 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2b310 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2b320 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2b330 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2b340 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2b350 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2b360 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2b370 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2b380 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2b390 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2b3a0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2b3b0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2b3c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b3d0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2b3e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2b3f0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2b400 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2b410 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2b420 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2b430 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2b440 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2b450 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2b460 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2b470 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2b480 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2b490 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2b4a0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2b4b0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2b4c0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2b4d0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2b4e0 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2b4f0 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2b500 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2b510 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2b520 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2b530 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2b540 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2b550 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2b560 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2b570 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2b580 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2b590 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2b5a0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2b5b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2b5c0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2b5d0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
2b5e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2b5f0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2b600 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2b610 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b620 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2b630 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2b640 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
2b650 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
2b660 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
2b670 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
2b680 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2b690 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
2b6a0 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
2b6b0 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
2b6c0 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
2b6d0 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
2b6e0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2b6f0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2b700 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
2b710 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
2b720 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
2b730 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
2b740 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2b750 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
2b760 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
2b770 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
2b780 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
2b790 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
2b7a0 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
2b7b0 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
2b7c0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
2b7d0 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
2b7e0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
2b7f0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2b800 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
2b810 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2b820 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
2b830 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
2b840 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b850 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2b860 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2b870 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2b880 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2b890 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2b8a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2b8b0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2b8c0 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2b8d0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
2b8e0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
2b8f0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
2b900 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
2b910 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
2b920 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
2b930 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
2b940 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
2b950 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
2b960 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2b970 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2b980 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2b990 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
2b9a0 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
2b9b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b9c0 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
2b9d0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
2b9e0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
2b9f0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
2ba00 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2ba10 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
2ba20 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
2ba30 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2ba40 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
2ba50 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
2ba60 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
2ba70 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
2ba80 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
2ba90 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
2baa0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
2bab0 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
2bac0 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
2bad0 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
2bae0 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
2baf0 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
2bb00 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2bb10 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
2bb20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
2bb30 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
2bb40 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
2bb50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2bb60 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
2bb70 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
2bb80 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2bb90 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
2bba0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2bbb0 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
2bbc0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
2bbd0 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
2bbe0 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
2bbf0 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
2bc00 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
2bc10 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
2bc20 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
2bc30 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
2bc40 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
2bc50 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
2bc60 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2bc70 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
2bc80 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
2bc90 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2bca0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2bcb0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2bcc0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2bcd0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2bce0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2bcf0 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
2bd00 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2bd10 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2bd20 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
2bd30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
2bd40 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
2bd50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bd60 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
2bd70 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2bd80 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2bd90 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
2bda0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2bdb0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2bdc0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
2bdd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2bde0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2bdf0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
2be00 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
2be10 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
2be20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2be30 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
2be40 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
2be50 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2be60 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2be70 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
2be80 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2be90 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2bea0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2beb0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2bec0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2bed0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2bee0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2bef0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
2bf00 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2bf10 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
2bf20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2bf30 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2bf40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2bf50 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2bf60 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2bf70 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2bf80 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2bf90 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2bfa0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2bfb0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2bfc0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2bfd0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2bfe0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2bff0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
2c000 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
2c010 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
2c020 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
2c030 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
2c040 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c050 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
2c060 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
2c070 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2c080 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
2c090 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
2c0a0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
2c0b0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
2c0c0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
2c0d0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
2c0e0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2c0f0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
2c100 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
2c110 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
2c120 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
2c130 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
2c140 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2c150 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
2c160 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2c170 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
2c180 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2c190 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
2c1a0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2c1b0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
2c1c0 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
2c1d0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2c1e0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
2c1f0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
2c200 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
2c210 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
2c220 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
2c230 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
2c240 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2c250 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
2c260 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
2c270 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
2c280 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
2c290 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
2c2a0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
2c2b0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
2c2c0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
2c2d0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
2c2e0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
2c2f0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
2c300 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
2c310 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2c320 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
2c330 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
2c340 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
2c350 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
2c360 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
2c370 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
2c380 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
2c390 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
2c3a0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
2c3b0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
2c3c0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
2c3d0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
2c3e0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
2c3f0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
2c400 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
2c410 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
2c420 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
2c430 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
2c440 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
2c450 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
2c460 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
2c470 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
2c480 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2c490 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
2c4a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2c4b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2c4c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2c4d0 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2c4e0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2c4f0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
2c500 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
2c510 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
2c520 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2c530 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
2c540 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
2c550 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2c560 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2c570 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2c580 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
2c590 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
2c5a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
2c5b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2c5c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2c5d0 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
2c5e0 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
2c5f0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
2c600 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
2c610 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
2c620 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
2c630 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
2c640 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
2c650 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
2c660 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
2c670 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
2c680 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2c690 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
2c6a0 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
2c6b0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
2c6c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c6d0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2c6e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2c6f0 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
2c700 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2c710 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
2c720 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2c730 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2c740 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2c750 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
2c760 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2c770 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
2c780 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
2c790 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2c7a0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
2c7b0 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
2c7c0 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
2c7d0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2c7e0 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
2c7f0 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
2c800 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
2c810 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
2c820 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
2c830 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
2c840 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
2c850 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
2c860 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
2c870 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
2c880 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
2c890 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
2c8a0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2c8b0 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
2c8c0 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
2c8d0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
2c8e0 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
2c8f0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
2c900 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
2c910 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
2c920 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
2c930 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
2c940 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
2c950 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2c960 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
2c970 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
2c980 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
2c990 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
2c9a0 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
2c9b0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
2c9c0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2c9d0 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
2c9e0 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
2c9f0 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
2ca00 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
2ca10 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
2ca20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
2ca30 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
2ca40 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
2ca50 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
2ca60 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
2ca70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2ca80 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
2ca90 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
2caa0 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
2cab0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2cac0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2cad0 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
2cae0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
2caf0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
2cb00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cb10 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2cb20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2cb30 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
2cb40 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
2cb50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
2cb60 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
2cb70 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
2cb80 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
2cb90 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
2cba0 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
2cbb0 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
2cbc0 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
2cbd0 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
2cbe0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
2cbf0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
2cc00 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
2cc10 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
2cc20 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2cc30 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
2cc40 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
2cc50 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
2cc60 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
2cc70 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
2cc80 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
2cc90 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
2cca0 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
2ccb0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
2ccc0 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
2ccd0 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
2cce0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
2ccf0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
2cd00 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
2cd10 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
2cd20 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
2cd30 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2cd40 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
2cd50 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
2cd60 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
2cd70 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2cd80 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
2cd90 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
2cda0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
2cdb0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
2cdc0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
2cdd0 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
2cde0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
2cdf0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
2ce00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2ce10 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
2ce20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2ce30 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
2ce40 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
2ce50 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2ce60 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
2ce70 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
2ce80 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2ce90 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
2cea0 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
2ceb0 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
2cec0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
2ced0 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
2cee0 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
2cef0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
2cf00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cf10 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
2cf20 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
2cf30 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2cf40 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
2cf50 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
2cf60 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
2cf70 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
2cf80 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
2cf90 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
2cfa0 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
2cfb0 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
2cfc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cfd0 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
2cfe0 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
2cff0 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
2d000 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
2d010 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
2d020 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
2d030 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
2d040 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
2d050 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
2d060 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2d070 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
2d080 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2d090 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
2d0a0 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
2d0b0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2d0c0 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
2d0d0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
2d0e0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
2d0f0 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
2d100 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
2d110 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d120 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
2d130 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d140 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
2d150 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
2d160 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
2d170 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2d180 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
2d190 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
2d1a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
2d1b0 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
2d1c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d1d0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
2d1e0 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
2d1f0 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
2d200 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
2d210 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
2d220 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
2d230 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
2d240 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
2d250 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
2d260 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
2d270 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
2d280 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
2d290 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
2d2a0 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
2d2b0 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
2d2c0 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
2d2d0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
2d2e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2d2f0 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
2d300 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
2d310 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
2d320 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
2d330 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
2d340 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
2d350 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
2d360 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
2d370 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
2d380 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
2d390 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
2d3a0 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
2d3b0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2d3c0 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
2d3d0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
2d3e0 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
2d3f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d400 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2d410 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
2d420 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
2d430 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
2d440 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
2d450 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
2d460 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
2d470 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
2d480 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
2d490 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
2d4a0 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
2d4b0 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
2d4c0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2d4d0 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
2d4e0 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
2d4f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
2d500 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
2d510 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d520 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2d530 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2d540 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
2d550 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
2d560 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2d570 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d580 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
2d590 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
2d5a0 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
2d5b0 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
2d5c0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2d5d0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
2d5e0 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
2d5f0 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
2d600 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2d610 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
2d620 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
2d630 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2d640 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2d650 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2d660 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a  a result set.**.
2d670 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d680 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
2d690 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d6a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2d6b0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
2d6c0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2d6d0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2d6e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d6f0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
2d700 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d710 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
2d720 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
2d730 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
2d740 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
2d750 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d760 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
2d770 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
2d780 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
2d790 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2d7a0 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
2d7b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2d7c0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2d7d0 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
2d7e0 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
2d7f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2d800 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2d810 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2d820 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2d830 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
2d840 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2d850 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2d860 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
2d870 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
2d880 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
2d890 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
2d8a0 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
2d8b0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
2d8c0 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2d8d0 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
2d8e0 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
2d8f0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
2d900 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
2d910 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
2d920 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
2d930 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
2d940 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
2d950 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
2d960 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
2d970 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
2d980 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
2d990 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
2d9a0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
2d9b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
2d9c0 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
2d9d0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2d9e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d9f0 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
2da00 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
2da10 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
2da20 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
2da30 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
2da40 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
2da50 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
2da60 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2da70 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
2da80 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2da90 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
2daa0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2dab0 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
2dac0 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
2dad0 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
2dae0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
2daf0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2db00 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
2db10 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
2db20 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
2db30 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
2db40 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
2db50 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
2db60 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
2db70 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
2db80 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
2db90 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
2dba0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
2dbb0 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
2dbc0 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
2dbd0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2dbe0 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
2dbf0 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
2dc00 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
2dc10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2dc20 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
2dc30 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
2dc40 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2dc50 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
2dc60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
2dc70 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
2dc80 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
2dc90 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2dca0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
2dcb0 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
2dcc0 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
2dcd0 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
2dce0 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
2dcf0 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
2dd00 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
2dd10 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2dd20 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2dd30 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
2dd40 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
2dd50 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22  the "result set"
2dd60 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2dd70 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2dd80 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2dd90 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
2dda0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
2ddb0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
2ddc0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
2ddd0 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
2dde0 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
2ddf0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
2de00 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
2de10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2de20 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
2de30 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
2de40 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
2de50 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
2de60 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
2de70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2de80 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
2de90 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
2dea0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2deb0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2dec0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
2ded0 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
2dee0 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
2def0 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
2df00 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2df10 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2df20 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
2df30 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
2df40 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2df50 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
2df60 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
2df70 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2df80 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
2df90 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
2dfa0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
2dfb0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
2dfc0 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
2dfd0 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
2dfe0 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
2dff0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
2e000 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
2e010 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
2e020 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
2e030 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
2e040 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
2e050 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2e060 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2e070 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
2e080 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
2e090 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2e0a0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
2e0b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e0c0 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
2e0d0 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
2e0e0 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
2e0f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2e100 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
2e110 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e120 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2e130 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
2e140 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
2e150 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2e160 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
2e170 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2e180 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
2e190 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2e1a0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
2e1b0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2e1c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e1d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2e1e0 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
2e1f0 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
2e200 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
2e210 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
2e220 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
2e230 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
2e240 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2e250 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2e260 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2e270 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
2e280 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
2e290 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
2e2a0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
2e2b0 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
2e2c0 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
2e2d0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
2e2e0 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
2e2f0 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
2e300 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
2e310 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
2e320 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
2e330 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
2e340 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
2e350 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
2e360 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
2e370 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2e380 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
2e390 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
2e3a0 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
2e3b0 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
2e3c0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
2e3d0 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
2e3e0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2e3f0 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
2e400 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2e410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2e420 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
2e430 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
2e440 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
2e450 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
2e460 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
2e470 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
2e480 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
2e490 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
2e4a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2e4b0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2e4c0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
2e4d0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2e4e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
2e4f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2e500 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2e510 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2e520 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2e530 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2e540 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2e550 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2e560 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
2e570 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2e580 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
2e590 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2e5a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2e5b0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2e5c0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2e5d0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2e5e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e5f0 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
2e600 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2e610 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2e620 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2e630 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
2e640 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2e650 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2e660 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2e670 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2e680 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2e690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e6a0 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
2e6b0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
2e6c0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2e6d0 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
2e6e0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2e6f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e700 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
2e710 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2e720 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2e730 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2e740 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2e750 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
2e760 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2e770 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e780 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
2e790 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2e7a0 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
2e7b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2e7c0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2e7d0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2e7e0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2e7f0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2e800 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2e810 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2e820 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2e830 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2e840 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
2e850 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2e860 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2e870 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2e880 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2e890 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2e8a0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2e8b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2e8c0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2e8d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
2e8e0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
2e8f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e900 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
2e910 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e920 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
2e930 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
2e940 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
2e950 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
2e960 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
2e970 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
2e980 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2e990 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2e9a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2e9b0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
2e9c0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
2e9d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
2e9e0 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
2e9f0 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
2ea00 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2ea10 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
2ea20 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
2ea30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ea40 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
2ea50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2ea60 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
2ea70 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
2ea80 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
2ea90 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
2eaa0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
2eab0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2eac0 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
2ead0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
2eae0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2eaf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65  .**.** ^The obje
2eb00 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
2eb10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2eb20 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
2eb30 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2eb40 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2eb50 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
2eb60 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2eb70 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
2eb80 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2eb90 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
2eba0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2ebb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2ebc0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
2ebd0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
2ebe0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2ebf0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2ec00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2ec10 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2ec20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
2ec30 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
2ec40 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
2ec50 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2ec60 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
2ec70 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2ec80 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2ec90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2eca0 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
2ecb0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2ecc0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
2ecd0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
2ece0 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
2ecf0 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
2ed00 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
2ed10 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
2ed20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
2ed30 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
2ed40 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
2ed50 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
2ed60 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
2ed70 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2ed80 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
2ed90 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
2eda0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
2edb0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2edc0 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
2edd0 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
2ede0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
2edf0 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
2ee00 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
2ee10 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2ee20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2ee30 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
2ee40 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
2ee50 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
2ee60 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
2ee70 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2ee80 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
2ee90 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
2eea0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
2eeb0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2eec0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2eed0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
2eee0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2eef0 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
2ef00 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2ef10 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2ef20 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
2ef30 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
2ef40 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
2ef50 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
2ef60 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2ef70 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
2ef80 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
2ef90 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
2efa0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
2efb0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2efc0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2efd0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2efe0 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
2eff0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2f000 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
2f010 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
2f020 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
2f030 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
2f040 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
2f050 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2f060 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2f070 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2f080 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2f090 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
2f0a0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
2f0b0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
2f0c0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
2f0d0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
2f0e0 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
2f0f0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2f100 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2f110 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
2f120 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
2f130 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2f140 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
2f150 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
2f160 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2f170 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2f180 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
2f190 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2f1a0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
2f1b0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
2f1c0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
2f1d0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2f1e0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2f1f0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
2f200 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
2f210 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2f220 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2f230 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2f240 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2f250 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2f260 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
2f270 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
2f280 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
2f290 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
2f2a0 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
2f2b0 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
2f2c0 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
2f2d0 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
2f2e0 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
2f2f0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
2f300 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
2f310 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
2f320 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
2f330 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
2f340 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
2f350 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
2f360 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
2f370 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
2f380 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
2f390 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
2f3a0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2f3b0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
2f3c0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
2f3d0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
2f3e0 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
2f3f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2f400 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
2f410 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2f420 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
2f430 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2f440 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
2f450 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
2f460 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
2f470 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
2f480 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
2f490 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
2f4a0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
2f4b0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2f4c0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2f4d0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
2f4e0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2f4f0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
2f500 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2f510 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2f520 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
2f530 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
2f540 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
2f550 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
2f560 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
2f570 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2f580 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
2f590 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2f5a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f5b0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2f5c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f5d0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2f5e0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2f5f0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2f600 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
2f610 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
2f620 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2f630 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
2f640 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2f650 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2f660 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2f670 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
2f680 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2f690 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2f6a0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2f6b0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
2f6c0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
2f6d0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
2f6e0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
2f6f0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
2f700 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
2f710 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
2f720 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
2f730 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
2f740 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
2f750 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2f760 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
2f770 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
2f780 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
2f790 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
2f7a0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
2f7b0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
2f7c0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
2f7d0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
2f7e0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
2f7f0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
2f800 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
2f810 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
2f820 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
2f830 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
2f840 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
2f850 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
2f860 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
2f870 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
2f880 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2f890 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
2f8a0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
2f8b0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2f8c0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2f8d0 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
2f8e0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2f8f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2f900 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2f910 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2f920 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2f930 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f940 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2f950 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2f960 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
2f970 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2f980 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
2f990 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2f9a0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2f9b0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
2f9c0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
2f9d0 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
2f9e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2f9f0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
2fa00 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
2fa10 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
2fa20 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
2fa30 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
2fa40 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
2fa50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fa60 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
2fa70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fa80 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
2fa90 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
2faa0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
2fab0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
2fac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2fad0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
2fae0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
2faf0 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
2fb00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fb10 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
2fb20 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
2fb30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fb40 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
2fb50 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2fb60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
2fb70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
2fb80 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
2fb90 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
2fba0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
2fbb0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
2fbc0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
2fbd0 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
2fbe0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2fbf0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2fc00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2fc10 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
2fc20 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
2fc30 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
2fc40 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
2fc50 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
2fc60 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2fc70 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
2fc80 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
2fc90 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2fca0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
2fcb0 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
2fcc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2fcd0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
2fce0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2fcf0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
2fd00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2fd10 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
2fd20 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
2fd30 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
2fd40 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2fd50 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
2fd60 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
2fd70 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
2fd80 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
2fd90 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
2fda0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
2fdb0 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
2fdc0 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
2fdd0 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
2fde0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2fdf0 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
2fe00 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
2fe10 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
2fe20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2fe30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2fe40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2fe50 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2fe60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fe70 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
2fe80 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2fe90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fea0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
2feb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2fec0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
2fed0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
2fee0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2fef0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2ff00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
2ff10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ff20 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
2ff30 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
2ff40 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
2ff50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ff60 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
2ff70 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2ff80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2ff90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ffa0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
2ffb0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2ffc0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
2ffd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2ffe0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2fff0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
30000 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30010 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
30020 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
30030 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
30040 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30050 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
30060 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
30070 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
30080 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
30090 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
300a0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
300b0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
300c0 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
300d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
300e0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
300f0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
30100 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
30110 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
30120 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
30130 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
30140 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
30150 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
30160 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
30170 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
30180 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
30190 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
301a0 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
301b0 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
301c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
301d0 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
301e0 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
301f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
30200 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
30210 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
30220 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
30230 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
30240 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
30250 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
30260 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
30270 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
30280 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
30290 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
302a0 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
302b0 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
302c0 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
302d0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
302e0 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
302f0 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
30300 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
30310 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
30320 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
30330 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
30340 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
30350 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
30360 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
30370 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
30380 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
30390 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
303a0 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
303b0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
303c0 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
303d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
303e0 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
303f0 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
30400 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
30410 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
30420 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
30430 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
30440 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
30450 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
30460 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
30470 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
30480 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
30490 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
304a0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
304b0 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
304c0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
304d0 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
304e0 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
304f0 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
30500 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
30510 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30520 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
30530 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
30540 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30550 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
30560 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
30570 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
30580 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
30590 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
305a0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
305b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
305c0 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
305d0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
305e0 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
305f0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
30600 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
30610 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
30620 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
30630 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
30640 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
30650 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
30660 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
30670 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
30680 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
30690 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
306a0 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
306b0 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
306c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
306d0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
306e0 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
306f0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
30700 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
30710 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
30720 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
30730 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
30740 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
30750 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30760 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
30770 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
30780 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
30790 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
307a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
307b0 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
307c0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
307d0 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
307e0 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
307f0 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
30800 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
30810 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
30820 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
30830 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
30840 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
30850 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
30860 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30870 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
30880 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
30890 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
308a0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
308b0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
308c0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
308d0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
308e0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
308f0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
30900 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
30910 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
30920 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
30930 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
30940 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30950 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
30960 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
30970 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
30980 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30990 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
309a0 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
309b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
309c0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
309d0 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
309e0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
309f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
30a00 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
30a10 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
30a20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
30a30 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
30a40 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
30a50 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
30a60 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
30a70 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
30a80 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
30a90 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
30aa0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
30ab0 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
30ac0 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
30ad0 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
30ae0 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
30af0 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
30b00 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
30b10 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
30b20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
30b30 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
30b40 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
30b50 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  r.** the second 
30b60 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
30b70 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
30b80 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
30b90 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
30ba0 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
30bb0 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
30bc0 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
30bd0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
30be0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
30bf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
30c00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
30c10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
30c20 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
30c30 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
30c40 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
30c50 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
30c60 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
30c70 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
30c80 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
30c90 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
30ca0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
30cb0 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
30cc0 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
30cd0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
30ce0 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
30cf0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
30d00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
30d10 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
30d20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
30d30 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
30d40 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
30d50 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
30d60 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
30d70 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
30d80 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
30d90 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
30da0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
30db0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
30dc0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
30dd0 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
30de0 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
30df0 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
30e00 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
30e10 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
30e20 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
30e30 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
30e40 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
30e50 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
30e60 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
30e70 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
30e80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
30e90 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
30ea0 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
30eb0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
30ec0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
30ed0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
30ee0 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
30ef0 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
30f00 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
30f10 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30f20 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
30f30 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
30f40 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
30f50 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
30f60 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
30f70 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
30f80 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
30f90 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
30fa0 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
30fb0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
30fc0 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
30fd0 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
30fe0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
30ff0 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
31000 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
31010 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
31020 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
31030 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
31040 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
31050 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
31060 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
31070 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
31080 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65  parameters.  The
31090 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
310a0 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72  uld set this par
310b0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51  ameter to.** [SQ
310c0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66  LITE_UTF16LE] if
310d0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
310e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
310f0 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  okes .** [sqlite
31100 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
31110 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
31120 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
31130 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69  6BE] if the.** i
31140 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
31150 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76  vokes [sqlite3_v
31160 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d  alue_text16be()]
31170 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
31180 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
31190 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76  6] if [sqlite3_v
311a0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69  alue_text16()] i
311b0 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49  s used, or [SQLI
311c0 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65  TE_UTF8].** othe
311d0 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d  rwise.  ^The sam
311e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d  e SQL function m
311f0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
31200 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
31210 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65  using.** differe
31220 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78  nt preferred tex
31230 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74  t encodings, wit
31240 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c  h different impl
31250 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a  ementations for.
31260 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67  ** each encoding
31270 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
31280 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
31290 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
312a0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
312b0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
312c0 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
312d0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
312e0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
312f0 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
31300 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rsion..**.** ^Th
31310 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
31320 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c  er may optionall
31330 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b  y be ORed with [
31340 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
31350 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e  STIC].** to sign
31360 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63  al that the func
31370 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73  tion will always
31380 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
31390 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a   result given.**
313a0 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
313b0 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65   within a single
313c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
313d0 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69   Most SQL functi
313e0 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72  ons are.** deter
313f0 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62  ministic.  The b
31400 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28  uilt-in [random(
31410 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  )] SQL function 
31420 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
31430 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74   a.** function t
31440 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72  hat is not deter
31450 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53  ministic.  The S
31460 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e  QLite query plan
31470 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  ner is able to.*
31480 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69  * perform additi
31490 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f  onal optimizatio
314a0 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73  ns on determinis
314b0 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73  tic functions, s
314c0 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20  o use.** of the 
314d0 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
314e0 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72  ISTIC] flag is r
314f0 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65  ecommended where
31500 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a   possible..**.**
31510 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
31520 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
31530 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
31540 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
31550 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
31560 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
31570 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
31580 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
31590 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
315a0 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
315b0 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
315c0 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
315d0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
315e0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
315f0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
31600 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
31610 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
31620 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
31630 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
31640 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
31650 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
31660 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
31670 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
31680 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
31690 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
316a0 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
316b0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
316c0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
316d0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
316e0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
316f0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
31700 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
31710 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
31720 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
31730 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
31740 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
31750 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
31760 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
31770 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
31780 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
31790 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
317a0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
317b0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
317c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
317d0 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
317e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
317f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
31800 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
31810 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
31820 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
31830 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
31840 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
31850 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
31860 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
31870 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
31880 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
31890 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
318a0 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
318b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
318c0 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
318d0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
318e0 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
318f0 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
31900 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
31910 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
31920 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
31930 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
31940 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
31950 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
31960 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
31970 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
31980 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
31990 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
319a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
319b0 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
319c0 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
319d0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
319e0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
319f0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
31a00 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
31a10 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
31a20 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
31a30 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
31a40 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
31a50 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
31a60 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
31a70 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
31a80 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
31a90 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
31aa0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
31ab0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
31ac0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
31ad0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
31ae0 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
31af0 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
31b00 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
31b10 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
31b20 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
31b30 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
31b40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
31b50 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
31b60 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
31b70 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
31b80 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
31b90 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
31ba0 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
31bb0 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
31bc0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
31bd0 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
31be0 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
31bf0 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
31c00 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
31c10 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
31c20 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
31c30 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
31c40 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
31c50 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
31c60 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
31c70 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
31c80 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
31c90 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
31ca0 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
31cb0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
31cc0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
31cd0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
31ce0 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
31cf0 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
31d00 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
31d10 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
31d20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
31d30 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
31d40 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31d50 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
31d60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31d70 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
31d80 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
31d90 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
31da0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
31db0 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
31dc0 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
31dd0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
31de0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
31df0 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
31e00 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
31e10 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
31e20 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
31e30 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
31e40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
31e50 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
31e60 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
31e70 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
31e80 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
31e90 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
31ea0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
31eb0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
31ec0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
31ed0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31ee0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
31ef0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
31f00 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31f10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31f20 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
31f30 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31f40 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
31f50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31f60 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
31f70 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
31f80 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
31f90 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
31fa0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
31fb0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
31fc0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
31fd0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
31fe0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
31ff0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
32000 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
32010 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32020 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32030 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
32040 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
32050 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32060 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
32070 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
32080 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
32090 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
320a0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
320b0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
320c0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
320d0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
320e0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
320f0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
32100 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
32110 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
32120 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
32130 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
32140 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
32150 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
32160 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
32170 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
32180 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
32190 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
321a0 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
321b0 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
321c0 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
321d0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
321e0 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
321f0 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
32200 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32210 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
32220 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   1    /* IMP: R-
32230 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23  37514-35566 */.#
32240 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
32250 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20  F16LE        2  
32260 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37    /* IMP: R-0337
32270 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69  1-37637 */.#defi
32280 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
32290 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a  E        3    /*
322a0 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34   IMP: R-51971-34
322b0 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  154 */.#define S
322c0 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
322d0 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
322e0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
322f0 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
32300 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
32310 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72      5    /* Depr
32320 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e  ecated */.#defin
32330 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
32340 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
32350 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
32360 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
32370 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32380 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73  : Function Flags
32390 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
323a0 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52  stants may be OR
323b0 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68  ed together with
323c0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
323d0 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65  _UTF8 | preferre
323e0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  d text encoding]
323f0 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61   as the fourth a
32400 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
32410 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32420 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  nction()], [sqli
32430 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32440 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
32450 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32460 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  function_v2()]..
32470 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32480 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20  E_DETERMINISTIC 
32490 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20     0x800../*.** 
324a0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
324b0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
324c0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
324d0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
324e0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
324f0 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
32500 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
32510 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
32520 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
32530 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
32540 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
32550 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
32560 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
32570 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
32580 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
32590 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
325a0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
325b0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
325c0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
325d0 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
325e0 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
325f0 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
32600 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
32610 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
32620 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
32630 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
32640 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
32650 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32660 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
32670 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
32680 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
32690 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
326a0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
326b0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
326c0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
326d0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
326e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
326f0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
32700 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
32710 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
32720 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
32730 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32740 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
32750 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
32760 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
32770 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
32780 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
32790 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
327a0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
327b0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
327c0 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71          void*,sq
327d0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
327e0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
327f0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
32800 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
32810 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
32820 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
32830 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
32840 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
32850 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
32860 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
32870 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
32880 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
32890 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
328a0 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
328b0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
328c0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
328d0 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
328e0 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
328f0 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
32900 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
32910 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
32920 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32930 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
32940 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32950 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
32960 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
32970 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
32980 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
32990 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
329a0 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
329b0 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
329c0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
329d0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
329e0 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
329f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32a00 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
32a10 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
32a20 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
32a30 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
32a40 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
32a50 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
32a60 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
32a70 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
32a80 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
32a90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32aa0 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
32ab0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
32ac0 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
32ad0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32ae0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
32af0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
32b00 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
32b10 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
32b20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32b30 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
32b40 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
32b50 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
32b60 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
32b70 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
32b80 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
32b90 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
32ba0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
32bb0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  * except that th
32bc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
32bd0 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
32be0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32bf0 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
32c00 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
32c10 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
32c20 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
32c30 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
32c40 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
32c50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
32c60 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
32c70 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
32c80 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
32c90 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
32ca0 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
32cb0 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
32cc0 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
32cd0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
32ce0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
32cf0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
32d00 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
32d10 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
32d20 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
32d30 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
32d40 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
32d50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
32d60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
32d70 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
32d80 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
32d90 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
32da0 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
32db0 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
32dc0 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
32dd0 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
32de0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
32df0 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
32e00 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
32e10 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
32e20 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
32e30 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
32e40 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
32e50 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
32e60 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
32e70 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
32e80 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
32e90 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
32ea0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
32eb0 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
32ec0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
32ed0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
32ee0 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
32ef0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
32f00 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
32f10 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
32f20 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
32f30 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
32f40 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
32f50 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
32f60 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
32f70 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
32f80 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
32f90 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
32fa0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
32fb0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32fc0 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
32fd0 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
32fe0 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
32ff0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
33000 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
33010 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33020 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
33030 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
33040 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
33050 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
33060 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
33070 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
33080 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
33090 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
330a0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
330b0 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
330c0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
330d0 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
330e0 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  s..*/.const void
330f0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
33100 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
33110 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
33120 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
33130 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
33140 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
33150 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
33160 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65  _value*);.double
33170 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
33180 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
33190 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
331a0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
331b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71  ite3_value*);.sq
331c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
331d0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
331e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
331f0 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
33200 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
33210 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
33220 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
33230 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
33240 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
33250 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
33260 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
33270 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
33280 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33290 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
332a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
332b0 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
332c0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
332d0 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
332e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
332f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
33300 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
33310 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
33320 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
33330 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
33340 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
33350 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
33360 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
33370 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
33380 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
33390 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
333a0 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
333b0 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
333c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
333d0 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
333e0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
333f0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
33400 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
33410 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
33420 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
33430 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
33440 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
33450 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
33460 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
33470 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
33480 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
33490 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
334a0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
334b0 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
334c0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
334d0 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
334e0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
334f0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
33500 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
33510 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
33520 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
33530 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33540 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
33550 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
33560 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
33570 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
33580 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
33590 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
335a0 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
335b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
335c0 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
335d0 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
335e0 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
335f0 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
33600 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
33610 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
33620 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
33630 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
33640 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
33650 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
33660 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
33670 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
33680 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33690 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
336a0 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
336b0 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
336c0 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
336d0 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
336e0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
336f0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
33700 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
33710 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a  a NULL pointer .
33720 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61  ** when first ca
33730 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73  lled if N is les
33740 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
33750 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
33760 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
33770 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
33780 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
33790 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
337a0 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
337b0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
337c0 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
337d0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
337e0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
337f0 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
33800 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
33810 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
33820 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
33830 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
33840 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33850 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
33860 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
33870 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
33880 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
33890 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
338a0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20  * allocation.)^ 
338b0 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e   Within the xFin
338c0 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20  al callback, it 
338d0 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20  is customary to 
338e0 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61  set.** N=0 in ca
338f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
33900 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33910 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f  (C,N) so that no
33920 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d   .** pointless m
33930 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
33940 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e  s occur..**.** ^
33950 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
33960 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
33970 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
33980 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
33990 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
339a0 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
339b0 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
339c0 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
339d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
339e0 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
339f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
33a00 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
33a10 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
33a20 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
33a30 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
33a40 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
33a50 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
33a60 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
33a70 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
33a80 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
33a90 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
33aa0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
33ab0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
33ac0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
33ad0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
33ae0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
33af0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
33b00 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
33b10 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
33b20 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
33b30 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
33b40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33b50 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
33b60 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
33b70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
33b80 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
33b90 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
33ba0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
33bb0 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
33bc0 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
33bd0 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
33be0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
33bf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
33c00 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
33c10 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
33c20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
33c30 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
33c40 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
33c50 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
33c60 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
33c70 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
33c80 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
33c90 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
33ca0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
33cb0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
33cc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33cd0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33ce0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
33cf0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
33d00 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
33d10 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
33d20 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
33d30 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
33d40 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
33d50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33d60 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
33d70 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
33d80 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
33d90 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
33da0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
33db0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
33dc0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
33dd0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
33de0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33df0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
33e00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33e10 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
33e20 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
33e30 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
33e40 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
33e50 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
33e60 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ion..*/.sqlite3 
33e70 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
33e80 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
33e90 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
33ea0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
33eb0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
33ec0 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
33ed0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  se functions may
33ee0 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e   be used by (non
33ef0 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20  -aggregate) SQL 
33f00 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
33f10 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
33f20 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
33f30 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
33f40 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
33f50 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
33f60 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
33f70 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
33f80 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
33f90 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
33fa0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
33fb0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
33fc0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
33fd0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
33fe0 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70  erved.  An examp
33ff0 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74  le.** of where t
34000 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65  his might be use
34010 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75  ful is in a regu
34020 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
34030 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  atching.** funct
34040 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
34050 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
34060 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
34070 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65  ion can be store
34080 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
34090 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
340a0 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72   the pattern str
340b0 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61  ing.  .** Then a
340c0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61  s long as the pa
340d0 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d  ttern string rem
340e0 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a  ains the same,.*
340f0 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72  * the compiled r
34100 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
34110 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
34120 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
34130 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
34140 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e  e same function.
34150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34160 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
34170 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
34180 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
34190 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
341a0 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
341b0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
341c0 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
341d0 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
341e0 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
341f0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
34200 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34210 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20  tion. ^If there 
34220 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a  is no metadata.*
34230 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
34240 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61  h the function a
34250 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71  rgument, this sq
34260 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
34270 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  a() interface.**
34280 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
34290 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
342a0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
342b0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
342c0 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
342d0 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66   P as metadata f
342e0 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
342f0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
34300 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34310 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53  ed function.  ^S
34320 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
34330 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
34340 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72  t_auxdata(C,N) r
34350 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65  eturn P from the
34360 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
34370 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34380 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c  ata(C,N,P,X) cal
34390 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  l if the metadat
343a0 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64  a is still valid
343b0 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74   or.** NULL if t
343c0 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  he metadata has 
343d0 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a  been discarded..
343e0 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63  ** ^After each c
343f0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
34400 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
34410 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e  ,X) where X is n
34420 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69  ot NULL,.** SQLi
34430 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
34440 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  he destructor fu
34450 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61  nction X with pa
34460 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c  rameter P exactl
34470 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20  y.** once, when 
34480 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
34490 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51  discarded..** SQ
344a0 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
344b0 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61  discard the meta
344c0 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65  data at any time
344d0 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c  , including: <ul
344e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74  >.** <li> when t
344f0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
34500 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
34510 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a  ter changes, or.
34520 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71  ** <li> when [sq
34530 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
34540 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
34550 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
34560 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
34570 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
34580 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
34590 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
345a0 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ata() is invoked
345b0 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61   again on the sa
345c0 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72  me parameter, or
345d0 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20  .** <li> during 
345e0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c  the original sql
345f0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34600 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d  () call when a m
34610 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61  emory .**      a
34620 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
34630 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a  occurs. </ul>)^.
34640 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c  **.** Note the l
34650 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61  ast bullet in pa
34660 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64  rticular.  The d
34670 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a  estructor X in .
34680 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
34690 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
346a0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
346b0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
346c0 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  ore the.** sqlit
346d0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
346e0 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20   interface even 
346f0 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20  returns.  Hence 
34700 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34710 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20  ata().** should 
34720 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74  be called near t
34730 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75  he end of the fu
34740 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
34750 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a  ation and the.**
34760 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
34770 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
34780 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65  not make any use
34790 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73   of P after.** s
347a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
347b0 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61  ta() has been ca
347c0 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  lled..**.** ^(In
347d0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
347e0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
347f0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
34800 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66  n calls for.** f
34810 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
34820 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70  rs that are comp
34830 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e  ile-time constan
34840 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69  ts, including li
34850 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
34860 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
34870 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73   and expressions
34880 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74   composed from t
34890 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a  he same.)^.**.**
348a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
348b0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
348c0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
348d0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
348e0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
348f0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
34900 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
34910 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
34920 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
34930 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
34940 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
34950 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
34960 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
34970 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
34980 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34990 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
349a0 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
349b0 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
349c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
349d0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
349e0 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
349f0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
34a00 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
34a10 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
34a20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
34a30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34a40 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
34a50 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
34a60 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
34a70 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
34a80 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
34a90 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
34aa0 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
34ab0 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
34ac0 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
34ad0 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
34ae0 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
34af0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
34b00 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
34b10 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
34b20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
34b30 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
34b40 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
34b50 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
34b60 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
34b70 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
34b80 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
34b90 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
34ba0 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
34bb0 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
34bc0 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
34bd0 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
34be0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a  + compilers..*/.
34bf0 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
34c00 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
34c10 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
34c20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
34c30 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
34c40 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
34c50 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
34c60 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
34c70 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
34c80 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
34c90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34ca0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
34cb0 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
34cc0 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
34cd0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
34ce0 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
34cf0 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
34d00 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
34d10 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
34d20 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
34d30 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
34d40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34d50 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
34d60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34d70 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
34d80 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
34d90 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
34da0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
34db0 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
34dc0 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
34dd0 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
34de0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
34df0 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
34e00 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
34e10 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
34e20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34e30 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
34e40 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
34e50 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
34e60 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
34e70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
34e80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34e90 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
34ea0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
34eb0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
34ec0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
34ed0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34ee0 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
34ef0 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
34f00 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
34f10 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
34f20 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
34f30 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
34f40 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
34f50 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
34f60 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
34f70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
34f80 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
34f90 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
34fa0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
34fb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34fc0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34fd0 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
34fe0 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
34ff0 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
35000 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
35010 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
35020 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
35030 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
35040 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
35050 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
35060 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
35070 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
35080 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35090 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
350a0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
350b0 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
350c0 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
350d0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
350e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
350f0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
35100 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35110 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
35120 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
35130 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
35140 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
35150 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
35160 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
35170 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
35180 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
35190 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
351a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
351b0 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
351c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
351d0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
351e0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
351f0 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
35200 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
35210 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
35220 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
35230 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35240 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
35250 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
35260 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
35270 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
35280 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
35290 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
352a0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
352b0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
352c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
352d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
352e0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
352f0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
35300 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
35310 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
35320 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
35330 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
35340 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
35350 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
35360 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
35370 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
35380 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
35390 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
353a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
353b0 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
353c0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
353d0 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
353e0 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
353f0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
35400 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
35410 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
35420 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
35430 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35440 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
35450 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35460 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
35470 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
35480 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
35490 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
354a0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
354b0 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
354c0 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
354d0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
354e0 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
354f0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
35500 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
35510 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
35520 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35530 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
35540 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
35550 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
35560 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
35570 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
35580 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
35590 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
355a0 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
355b0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
355c0 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
355d0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
355e0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
355f0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
35600 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35610 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
35620 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
35630 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
35640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35650 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
35660 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
35670 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
35680 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
35690 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
356a0 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
356b0 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f  r BLOB is too lo
356c0 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
356d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
356e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
356f0 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
35700 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
35710 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
35720 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
35730 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
35740 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
35750 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35760 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
35770 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35780 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
35790 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
357a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
357b0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
357c0 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
357d0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
357e0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
357f0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
35800 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35810 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
35820 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
35830 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
35840 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
35850 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35860 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
35870 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
35880 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
35890 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
358a0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
358b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
358c0 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
358d0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
358e0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
358f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35900 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
35910 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
35920 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35930 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
35940 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35950 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
35960 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
35970 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
35980 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
35990 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
359a0 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
359b0 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
359c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
359d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
359e0 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
359f0 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
35a00 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
35a10 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
35a20 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
35a30 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
35a40 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
35a50 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
35a60 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  vely..** ^The sq
35a70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35a80 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
35a90 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
35aa0 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61  value of an.** a
35ab0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35ac0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
35ad0 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  e a text string 
35ae0 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a  in an encoding.*
35af0 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  * specified by t
35b00 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61  he fifth (and la
35b10 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77  st) parameter, w
35b20 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65  hich must be one
35b30 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  .** of [SQLITE_U
35b40 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
35b50 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
35b60 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
35b70 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20  TE_UTF16LE]..** 
35b80 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
35b90 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
35ba0 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
35bb0 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
35bc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
35bd0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
35be0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
35bf0 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
35c00 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
35c10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35c20 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35c30 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
35c40 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
35c50 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
35c60 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
35c70 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
35c80 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
35c90 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
35ca0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
35cb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
35cc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35cd0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
35ce0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
35cf0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
35d00 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
35d10 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
35d20 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
35d30 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
35d40 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
35d50 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
35d60 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
35d70 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
35d80 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
35d90 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
35da0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
35db0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
35dc0 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
35dd0 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
35de0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
35df0 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
35e00 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
35e10 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
35e20 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
35e30 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
35e40 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
35e50 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
35e60 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
35e70 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
35e80 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
35e90 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
35ea0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
35eb0 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
35ec0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
35ed0 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
35ee0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
35ef0 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
35f00 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
35f10 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
35f20 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
35f30 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
35f40 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
35f50 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
35f60 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
35f70 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
35f80 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
35f90 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
35fa0 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
35fb0 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
35fc0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
35fd0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
35fe0 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
35ff0 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
36000 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
36010 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
36020 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
36030 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36040 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
36050 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
36060 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
36070 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
36080 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
36090 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
360a0 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
360b0 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
360c0 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
360d0 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
360e0 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
360f0 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
36100 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
36110 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
36120 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
36130 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
36140 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
36150 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
36160 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
36170 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
36180 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36190 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
361a0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
361b0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
361c0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
361d0 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
361e0 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
361f0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
36200 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
36210 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
36220 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
36230 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
36240 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
36250 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
36260 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
36270 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
36280 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
36290 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
362a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
362b0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
362c0 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
362d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
362e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
362f0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
36300 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
36310 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
36320 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
36330 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
36340 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
36350 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
36360 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
36370 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
36380 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
36390 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
363a0 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
363b0 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
363c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
363d0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
363e0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
363f0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36400 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36410 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
36420 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
36430 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
36440 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
36450 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
36460 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
36470 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
36480 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
36490 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
364a0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
364b0 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
364c0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
364d0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
364e0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
364f0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
36500 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
36510 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36520 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
36530 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
36540 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
36550 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
36560 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
36570 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  efined..*/.void 
36580 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
36590 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
365a0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
365b0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
365c0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
365d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
365e0 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  b64(sqlite3_cont
365f0 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ext*,const void*
36600 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
36610 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
36620 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64  ite3_uint64,void
36630 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
36640 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36650 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
36660 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
36670 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36680 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
36690 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
366a0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
366b0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
366c0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
366d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
366e0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
366f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36700 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
36710 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
36720 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
36730 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36740 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
36750 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
36760 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36770 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
36780 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
36790 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
367a0 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
367b0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
367c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
367d0 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
367e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
367f0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
36800 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36810 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
36820 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
36830 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36840 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
36850 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
36860 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
36870 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
36880 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36  te3_result_text6
36890 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
368a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
368b0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
368c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
368d0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
368e0 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67  *)(void*), unsig
368f0 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e  ned char encodin
36900 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  g);.void sqlite3
36910 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
36920 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36930 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
36940 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
36950 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
36960 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
36970 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36980 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
36990 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
369a0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
369b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
369c0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
369d0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
369e0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
369f0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
36a00 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
36a10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36a20 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
36a30 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36a40 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
36a50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36a60 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
36a70 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
36a80 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
36a90 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
36aa0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
36ab0 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72   add, remove, or
36ac0 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61   modify a [colla
36ad0 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
36ae0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
36af0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36b00 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
36b10 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
36b20 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
36b30 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  ame of the colla
36b40 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20  tion is a UTF-8 
36b50 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
36b60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36b70 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
36b80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36b90 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
36ba0 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
36bb0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
36bc0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
36bd0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36be0 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  ion16()..** ^Col
36bf0 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61  lation names tha
36c00 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  t compare equal 
36c10 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71  according to [sq
36c20 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29  lite3_strnicmp()
36c30 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  ] are.** conside
36c40 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61  red to be the sa
36c50 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  me name..**.** ^
36c60 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  (The third argum
36c70 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d  ent (eTextRep) m
36c80 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
36c90 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20  e constants:.** 
36ca0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
36cb0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c  LITE_UTF8],.** <
36cc0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
36cd0 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6LE],.** <li> [S
36ce0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
36cf0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
36d00 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  UTF16], or.** <l
36d10 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
36d20 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f  _ALIGNED]..** </
36d30 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54  ul>)^.** ^The eT
36d40 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20  extRep argument 
36d50 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65  determines the e
36d60 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e  ncoding of strin
36d70 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20  gs passed.** to 
36d80 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
36d90 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c  nction callback,
36da0 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e   xCallback..** ^
36db0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
36dc0 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55  6] and [SQLITE_U
36dd0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
36de0 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65  lues for eTextRe
36df0 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e  p.** force strin
36e00 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77  gs to be UTF16 w
36e10 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20  ith native byte 
36e20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b  order..** ^The [
36e30 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
36e40 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20  GNED] value for 
36e50 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20  eTextRep forces 
36e60 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e  strings to begin
36e70 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62  .** on an even b
36e80 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a  yte address..**.
36e90 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61  ** ^The fourth a
36ea0 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69  rgument, pArg, i
36eb0 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
36ec0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
36ed0 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  at is passed.** 
36ee0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
36ef0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
36f00 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
36f10 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
36f20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
36f30 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61  th argument, xCa
36f40 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69  llback, is a poi
36f50 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c  nter to the coll
36f60 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a  ating function..
36f70 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c  ** ^Multiple col
36f80 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
36f90 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
36fa0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  ed using the sam
36fb0 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69  e name but.** wi
36fc0 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  th different eTe
36fd0 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73  xtRep parameters
36fe0 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c   and SQLite will
36ff0 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a   use whichever.*
37000 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  * function requi
37010 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  res the least am
37020 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61  ount of data tra
37030 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20  nsformation..** 
37040 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63  ^If the xCallbac
37050 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55  k argument is NU
37060 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c  LL then the coll
37070 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
37080 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e  s.** deleted.  ^
37090 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  When all collati
370a0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76  ng functions hav
370b0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
370c0 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a  e are deleted,.*
370d0 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e  * that collation
370e0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73   is no longer us
370f0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
37100 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37110 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ion callback is 
37120 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63  invoked with a c
37130 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20  opy of the pArg 
37140 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
37150 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64  data pointer and
37160 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67   with two string
37170 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  s in the encodin
37180 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  g specified.** b
37190 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61  y the eTextRep a
371a0 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f  rgument.  The co
371b0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
371c0 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a   must return an.
371d0 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  ** integer that 
371e0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  is negative, zer
371f0 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a  o, or positive.*
37200 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  * if the first s
37210 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
37220 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  an, equal to, or
37230 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
37240 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73  e second,.** res
37250 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f  pectively.  A co
37260 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37270 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74   must always ret
37280 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73  urn the same ans
37290 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65  wer.** given the
372a0 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49   same inputs.  I
372b0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f  f two or more co
372c0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
372d0 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
372e0 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
372f0 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28  collation name (
37300 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20  using different 
37310 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29  eTextRep values)
37320 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73   then all.** mus
37330 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61  t give an equiva
37340 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e  lent answer when
37350 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71   invoked with eq
37360 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73  uivalent strings
37370 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69  ..** The collati
37380 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
37390 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77   obey the follow
373a0 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66  ing properties f
373b0 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67  or all.** string
373c0 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a  s A, B, and C:.*
373d0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
373e0 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42  > If A==B then B
373f0 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==A..** <li> If 
37400 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68  A==B and B==C th
37410 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e  en A==C..** <li>
37420 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20   If A&lt;B THEN 
37430 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  B&gt;A..** <li> 
37440 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26  If A&lt;B and B&
37450 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43  lt;C then A&lt;C
37460 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
37470 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20   If a collating 
37480 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61  function fails a
37490 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ny of the above 
374a0 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
374b0 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e  that.** collatin
374c0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72  g function is  r
374d0 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73  egistered and us
374e0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
374f0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
37500 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
37510 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37520 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37530 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
37540 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
37550 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
37560 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69  ** with the addi
37570 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44  tion that the xD
37580 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
37590 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41  is invoked on pA
375a0 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63  rg when.** the c
375b0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
375c0 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  n is deleted..**
375d0 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63   ^Collating func
375e0 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65  tions are delete
375f0 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
37600 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
37610 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ter.** calls to 
37620 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  the collation cr
37630 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
37640 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20   or when the.** 
37650 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37660 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20  tion] is closed 
37670 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
37680 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  lose()]..**.** ^
37690 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  The xDestroy cal
376a0 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c  lback is <u>not<
376b0 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68  /u> called if th
376c0 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  e .** sqlite3_cr
376d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
376e0 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  2() function fai
376f0 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ls.  Application
37700 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a  s that invoke.**
37710 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37720 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
37730 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78  ith a non-NULL x
37740 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74  Destroy argument
37750 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63   should .** chec
37760 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
37770 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66  e and dispose of
37780 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37790 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   data pointer.**
377a0 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68   themselves rath
377b0 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e  er than expectin
377c0 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c  g SQLite to deal
377d0 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65   with it for the
377e0 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69  m..** This is di
377f0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65  fferent from eve
37800 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ry other SQLite 
37810 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
37820 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a  inconsistency .*
37830 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65  * is unfortunate
37840 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63   but cannot be c
37850 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62  hanged without b
37860 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64  reaking backward
37870 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  s .** compatibil
37880 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ity..**.** See a
37890 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63  lso:  [sqlite3_c
378a0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
378b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
378c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
378d0 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
378e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
378f0 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
37900 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
37910 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
37920 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
37930 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
37940 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
37950 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
37960 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
37970 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
37980 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37990 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
379a0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
379b0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
379c0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
379d0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
379e0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
379f0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
37a00 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
37a10 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
37a20 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
37a30 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37a40 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
37a50 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
37a60 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
37a70 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
37a80 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
37a90 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
37aa0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37ab0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37ac0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
37ad0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
37ae0 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
37af0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
37b00 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
37b10 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
37b20 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
37b30 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
37b40 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
37b50 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
37b60 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
37b70 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
37b80 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
37b90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37ba0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
37bb0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
37bc0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
37bd0 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
37be0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
37bf0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
37c00 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
37c10 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
37c20 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37c30 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
37c40 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
37c50 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
37c60 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
37c70 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
37c80 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
37c90 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
37ca0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37cb0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
37cc0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
37cd0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
37ce0 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
37cf0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
37d00 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
37d10 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
37d20 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
37d30 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
37d40 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
37d50 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
37d60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
37d70 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
37d80 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
37d90 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
37da0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
37db0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
37dc0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37dd0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
37de0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37df0 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
37e00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
37e10 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
37e20 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
37e30 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
37e40 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
37e50 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
37e60 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
37e70 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
37e80 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
37e90 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
37ea0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
37eb0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
37ec0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
37ed0 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
37ee0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
37ef0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
37f00 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
37f10 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
37f20 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
37f30 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
37f40 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
37f50 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
37f60 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
37f70 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37f80 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
37f90 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37fa0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
37fb0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37fc0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
37fd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
37fe0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
37ff0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
38000 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
38010 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
38020 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
38030 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
38040 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
38050 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
38060 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
38070 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
38080 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
38090 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
380a0 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
380b0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
380c0 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
380d0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
380e0 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
380f0 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
38100 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
38110 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
38120 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
38130 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
38140 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
38150 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
38160 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
38170 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
38180 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
38190 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
381a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
381b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
381c0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
381d0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
381e0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
381f0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
38200 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69   The key */.);.i
38210 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76  nt sqlite3_key_v
38220 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
38230 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
38240 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
38250 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
38260 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
38270 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  DbName,         
38280 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
38290 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
382a0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
382b0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
382c0 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
382d0 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
382e0 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
382f0 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
38300 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
38310 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
38320 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
38330 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
38340 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
38350 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
38360 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
38370 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
38380 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
38390 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
383a0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
383b0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
383c0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
383d0 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
383e0 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
383f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
38400 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
38410 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
38420 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
38430 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
38440 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
38450 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
38460 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
38470 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  y_v2(.  sqlite3 
38480 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
38490 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
384a0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
384b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
384c0 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
384d0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
384e0 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  the database */.
384f0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
38500 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
38510 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
38520 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
38530 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
38540 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
38550 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
38560 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
38570 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
38580 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
38590 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
385a0 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
385b0 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
385c0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
385d0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
385e0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
385f0 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
38600 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
38610 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
38620 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
38630 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
38640 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
38650 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
38660 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
38670 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
38680 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
38690 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
386a0 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
386b0 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
386c0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
386d0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
386e0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
386f0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
38700 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
38710 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
38720 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
38730 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
38740 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
38750 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
38760 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
38770 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
38780 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
38790 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
387a0 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
387b0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
387c0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  h