/ Hex Artifact Content
Login

Artifact 356e69db9500b3fd11705c21ca247e19b95884a3:


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 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8ab0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8ac0: 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54  LOCKSTATE]].** T
8ad0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8ae0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
8af0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
8b00: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
8b10: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
8b20: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8b30: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
8b40: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
8b50: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
8b60: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
8b70: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
8b80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8b90: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
8ba0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
8bb0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
8bc0: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
8bd0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8be0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
8bf0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
8c00: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
8c10: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
8c20: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
8c30: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
8c40: 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76  g and is only av
8c50: 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65  ailable when the
8c60: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
8c70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
8c80: 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
8c90: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8ca0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8cb0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8cc0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8cd0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8ce0: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
8cf0: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
8d00: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
8d10: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
8d20: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
8d30: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
8d40: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
8d50: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
8d60: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
8d70: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
8d80: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
8d90: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
8da0: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
8db0: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
8dc0: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
8dd0: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
8de0: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
8df0: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
8e00: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
8e10: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
8e20: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
8e30: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
8e40: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8e50: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
8e60: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8e70: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
8e80: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8e90: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
8ea0: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
8eb0: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
8ec0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8ed0: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
8ee0: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
8ef0: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
8f00: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
8f10: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
8f20: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8f30: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
8f40: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
8f50: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
8f60: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
8f70: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
8f80: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
8f90: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
8fa0: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
8fb0: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
8fc0: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
8fd0: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
8fe0: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
8ff0: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
9000: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
9010: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
9020: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
9030: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
9040: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
9050: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
9060: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9070: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9080: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9090: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
90a0: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
90b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
90c0: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
90d0: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
90e0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
90f0: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68  nection.  See th
9100: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
9110: 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d  control()] docum
9120: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
9130: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
9140: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  mation..**.** <l
9150: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9160: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
9170: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
9180: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
9190: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
91a0: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
91b0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
91c0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
91d0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
91e0: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
91f0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9200: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9210: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9220: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9230: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
9240: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
9250: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
9260: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
9270: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
9280: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
9290: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
92a0: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
92b0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
92c0: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
92d0: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
92e0: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
92f0: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9300: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9310: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9320: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9330: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
9340: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9350: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
9360: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
9370: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
9380: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
9390: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
93a0: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
93b0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
93c0: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
93d0: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
93e0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
93f0: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9400: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9410: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9420: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9430: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
9440: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9450: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9460: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
9470: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9480: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9490: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
94a0: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
94b0: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
94c0: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
94d0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
94e0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
94f0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9500: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9510: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9520: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9530: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9540: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9550: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
9560: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9570: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
9580: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
9590: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
95a0: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
95b0: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
95c0: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
95d0: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
95e0: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
95f0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9600: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9610: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9620: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9630: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9640: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9650: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9660: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9670: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9680: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9690: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
96a0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
96b0: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
96c0: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
96d0: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
96e0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
96f0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9700: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9710: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9720: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9730: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9740: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9750: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
9760: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
9770: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9780: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9790: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
97a0: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
97b0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
97c0: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
97d0: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
97e0: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
97f0: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9800: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9810: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9820: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9830: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
9840: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
9850: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
9860: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
9870: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
9880: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
9890: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
98a0: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
98b0: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
98c0: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
98d0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
98e0: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
98f0: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9900: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9910: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9920: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9930: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9940: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9950: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
9960: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9970: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9980: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9990: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
99a0: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
99b0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
99c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
99d0: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
99e0: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
99f0: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9a00: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9a10: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9a20: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9a30: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9a40: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9a50: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9a60: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9a70: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9a80: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9a90: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9aa0: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9ab0: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9ac0: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9ad0: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9ae0: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9af0: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9b00: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9b10: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9b20: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9b30: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9b40: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9b50: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9b60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9b70: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9b80: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9b90: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9ba0: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9bb0: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9bc0: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
9bd0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
9be0: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9bf0: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9c00: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9c10: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
9c20: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
9c30: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
9c40: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
9c50: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
9c60: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
9c70: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9c80: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9c90: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9ca0: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9cb0: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9cc0: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
9cd0: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
9ce0: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9cf0: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9d00: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
9d10: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
9d20: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
9d30: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
9d40: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
9d50: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
9d60: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
9d70: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9d80: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
9d90: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
9da0: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
9db0: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
9dc0: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
9dd0: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
9de0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9df0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9e00: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9e10: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9e20: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9e30: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9e40: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9e50: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
9e60: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9e70: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9e80: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
9e90: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9ea0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9eb0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9ec0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9ed0: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
9ee0: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
9ef0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9f00: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9f10: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
9f20: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9f30: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9f40: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9f50: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9f60: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9f70: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
9f80: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
9f90: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
9fa0: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
9fb0: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
9fc0: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
9fd0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
9fe0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
9ff0: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a000: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a010: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a020: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a030: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a040: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a050: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a060: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a070: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a080: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a090: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a0a0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a0b0: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a0c0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a0d0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a0e0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a0f0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a100: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a110: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a120: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a130: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a140: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a150: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a170: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a180: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a190: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a1a0: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a1b0: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a1c0: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a1d0: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a1e0: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a1f0: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a200: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a210: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a220: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a230: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a240: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a250: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a260: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a270: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a280: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a290: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a2a0: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a2b0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a2c0: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a2d0: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a2e0: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a2f0: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a300: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a310: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a320: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a330: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a340: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a350: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a360: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a370: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a380: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a390: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a3a0: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a3b0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a3c0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a3d0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a3e0: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a3f0: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a400: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a410: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a420: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a430: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a440: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a450: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a460: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a470: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a480: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a490: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a4a0: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a4b0: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a4c0: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a4d0: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a4e0: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a4f0: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a500: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a510: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a520: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a530: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a540: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a550: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
a560: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
a570: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
a580: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
a590: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
a5a0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
a5b0: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
a5c0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
a5d0: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
a5e0: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
a5f0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
a600: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
a610: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
a620: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
a630: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
a640: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a650: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a660: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
a670: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
a680: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
a690: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
a6a0: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
a6b0: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
a6c0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
a6d0: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
a6e0: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
a6f0: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
a700: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
a710: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
a720: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
a730: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
a740: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
a750: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a760: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
a770: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
a780: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
a790: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
a7a0: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
a7b0: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
a7c0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
a7d0: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
a7e0: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
a7f0: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
a800: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
a810: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
a820: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
a830: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
a840: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
a850: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
a860: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
a870: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a880: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a890: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
a8a0: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
a8b0: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
a8c0: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
a8d0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
a8e0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
a8f0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a900: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a910: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
a920: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
a930: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
a940: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
a950: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
a960: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
a970: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
a980: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a990: 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69  t if result stri
a9a0: 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74  ng is NULL, or t
a9b0: 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f  hat returns a co
a9c0: 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  py.** of the res
a9d0: 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68  ult string if th
a9e0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d  e string is non-
a9f0: 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  NULL..** ^If the
aa00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
aa10: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
aa20: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  rol returns.** a
aa30: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f  ny result code o
aa40: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
aa50: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45  E_OK] or [SQLITE
aa60: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74  _NOTFOUND], that
aa70: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74   means.** that t
aa80: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72  he VFS encounter
aa90: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c  ed an error whil
aaa0: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b  e handling the [
aab0: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a  PRAGMA] and the.
aac0: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f  ** compilation o
aad0: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69  f the PRAGMA fai
aae0: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ls with an error
aaf0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
ab00: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
ab10: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63   file control oc
ab20: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69  curs at the begi
ab30: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20  nning of pragma 
ab40: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73  statement analys
ab50: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20  is and so.** it 
ab60: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72  is able to overr
ab70: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52  ide built-in [PR
ab80: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73  AGMA] statements
ab90: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
aba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
abb0: 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  ANDLER]].** ^The
abc0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
abd0: 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66  USYHANDLER].** f
abe0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20  ile-control may 
abf0: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  be invoked by SQ
ac00: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61  Lite on the data
ac10: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  base file handle
ac20: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65  .** shortly afte
ac30: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69  r it is opened i
ac40: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
ac50: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20  de a custom VFS 
ac60: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74  with access.** t
ac70: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  o the connection
ac80: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63  s busy-handler c
ac90: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67  allback. The arg
aca0: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65  ument is of type
acb0: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20   (void **).** - 
acc0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20  an array of two 
acd0: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e  (void *) values.
ace0: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64   The first (void
acf0: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69   *) actually poi
ad00: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63  nts.** to a func
ad10: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e  tion of type (in
ad20: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20  t (*)(void *)). 
ad30: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f  In order to invo
ad40: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ke the connectio
ad50: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c  ns.** busy-handl
ad60: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  er, this functio
ad70: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f  n should be invo
ad80: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63  ked with the sec
ad90: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a  ond (void *) in.
ada0: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20  ** the array as 
adb0: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  the only argumen
adc0: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  t. If it returns
add0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
ade0: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
adf0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69   should be retri
ae00: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  ed. If it return
ae10: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74  s zero, the cust
ae20: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62  om VFS should ab
ae30: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72  andon the.** cur
ae40: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a  rent operation..
ae50: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
ae60: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
ae70: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c  ENAME]].** ^Appl
ae80: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f  ication can invo
ae90: 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  ke the [SQLITE_F
aea0: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
aeb0: 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  E] file-control.
aec0: 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74  ** to have SQLit
aed0: 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20  e generate a.** 
aee0: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
aef0: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  me using the sam
af00: 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74  e algorithm that
af10: 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20   is followed to 
af20: 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70  generate.** temp
af30: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20  orary filenames 
af40: 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20  for TEMP tables 
af50: 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e  and other intern
af60: 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a  al uses.  The.**
af70: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
af80: 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69   be a char** whi
af90: 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65  ch will be fille
afa0: 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e  d with the filen
afb0: 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69  ame.** written i
afc0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
afd0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
afe0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
aff0: 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a  e caller should.
b000: 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ** invoke [sqlit
b010: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68  e3_free()] on th
b020: 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69  e result to avoi
b030: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e  d a memory leak.
b040: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b050: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b060: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
b070: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
b080: 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
b090: 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75  ol is used to qu
b0a0: 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a  ery or set the.*
b0b0: 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  * maximum number
b0c0: 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77   of bytes that w
b0d0: 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20  ill be used for 
b0e0: 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f  memory-mapped I/
b0f0: 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  O..** The argume
b100: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
b110: 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79  to a value of ty
b120: 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  pe sqlite3_int64
b130: 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61   that.** is an a
b140: 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20  dvisory maximum 
b150: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b160: 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d  in the file to m
b170: 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a  emory map.  The.
b180: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76  ** pointer is ov
b190: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
b1a0: 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54  he old value.  T
b1b0: 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  he limit is not 
b1c0: 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68  changed if.** th
b1d0: 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c  e value original
b1e0: 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73  ly pointed to is
b1f0: 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73   negative, and s
b200: 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69  o the current li
b210: 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71  mit .** can be q
b220: 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e  ueried by passin
b230: 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  g in a pointer t
b240: 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  o a negative num
b250: 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69  ber.  This.** fi
b260: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le-control is us
b270: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
b280: 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47   implement [PRAG
b290: 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a  MA mmap_size]..*
b2a0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b2b0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a  E_FCNTL_TRACE]].
b2c0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b2d0: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65  CNTL_TRACE] file
b2e0: 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65   control provide
b2f0: 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72  s advisory infor
b300: 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65  mation.** to the
b310: 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20   VFS about what 
b320: 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72  the higher layer
b330: 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  s of the SQLite 
b340: 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e  stack are doing.
b350: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f  .** This file co
b360: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79  ntrol is used by
b370: 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69   some VFS activi
b380: 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d  ty tracing [shim
b390: 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  s]..** The argum
b3a0: 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65  ent is a zero-te
b3b0: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e  rminated string.
b3c0: 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20    Higher layers 
b3d0: 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  in the.** SQLite
b3e0: 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72   stack may gener
b3f0: 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66  ate instances of
b400: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
b410: 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51  ol if.** the [SQ
b420: 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54  LITE_USE_FCNTL_T
b430: 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
b440: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
b450: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  bled..**.** <li>
b460: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  [[SQLITE_FCNTL_H
b470: 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68  AS_MOVED]].** Th
b480: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b490: 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20  HAS_MOVED] file 
b4a0: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65  control interpre
b4b0: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  ts its argument 
b4c0: 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  as a.** pointer 
b4d0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
b4e0: 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f  d it writes a bo
b4f0: 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20  olean into that 
b500: 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e  integer dependin
b510: 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  g.** on whether 
b520: 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20  or not the file 
b530: 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64  has been renamed
b540: 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65  , moved, or dele
b550: 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20  ted since it.** 
b560: 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64  was first opened
b570: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b580: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b590: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a  _SET_HANDLE]].**
b5a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b5b0: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
b5c0: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  DLE] opcode is u
b5d0: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
b5e0: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
b5f0: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
b600: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
b610: 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69  d to swap the fi
b620: 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74  le handle with t
b630: 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65  he one.** pointe
b640: 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67  d to by the pArg
b650: 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73   argument.  This
b660: 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75   capability is u
b670: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
b680: 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e  ng.** and only n
b690: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
b6a0: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
b6b0: 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64  _TEST is defined
b6c0: 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ..**.** </ul>.*/
b6d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b6e0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
b6f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
b700: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b710: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
b720: 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23  XYFILE       2.#
b730: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b740: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
b750: 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64  YFILE       3.#d
b760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b770: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TL_LAST_ERRNO   
b780: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
b790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b7a0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
b7b0: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
b7c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b7d0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
b7e0: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
b7f0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b800: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
b810: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
b820: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
b830: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
b840: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
b850: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
b860: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
b870: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
b880: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
b890: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
b8a0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
b8b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
b8c0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
b8d0: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
b8e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
b8f0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
b900: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
b910: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
b920: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
b930: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
b940: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
b950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b960: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
b970: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
b980: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
b990: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
b9a0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b9b0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
b9c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9d0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
b9e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
b9f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ba00: 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20  CNTL_TRACE      
ba10: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23              19.#
ba20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ba30: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20  NTL_HAS_MOVED   
ba40: 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64             20.#d
ba50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ba60: 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20  TL_SYNC         
ba70: 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65            21.#de
ba80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ba90: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
baa0: 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66  O        22.#def
bab0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bac0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
bad0: 45 20 20 20 20 20 20 20 32 33 0a 0a 2f 2a 20 64  E       23../* d
bae0: 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20  eprecated names 
baf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
bb00: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
bb10: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
bb20: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
bb30: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
bb40: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
bb50: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
bb60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
bb70: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
bb80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
bb90: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
bba0: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
bbb0: 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a  LAST_ERRNO.../*.
bbc0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
bbd0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
bbe0: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
bbf0: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
bc00: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
bc10: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
bc20: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
bc30: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
bc40: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
bc50: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
bc60: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
bc70: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
bc80: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
bc90: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
bca0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
bcb0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
bcc0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
bcd0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
bce0: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
bcf0: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
bd00: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
bd10: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
bd20: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
bd30: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
bd40: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
bd50: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
bd60: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
bd70: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
bd80: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
bd90: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
bda0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
bdb0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
bdc0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
bdd0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
bde0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
bdf0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
be00: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
be10: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
be20: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
be30: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
be40: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
be50: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
be60: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
be70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
be80: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
be90: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
bea0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
beb0: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
bec0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
bed0: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
bee0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
bef0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
bf00: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
bf10: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
bf20: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
bf30: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
bf40: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
bf50: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
bf60: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
bf70: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
bf80: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
bf90: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
bfa0: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
bfb0: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
bfc0: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
bfd0: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
bfe0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
bff0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
c000: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
c010: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
c020: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
c030: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
c040: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
c050: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
c060: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
c070: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
c080: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
c090: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
c0a0: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
c0b0: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
c0c0: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
c0d0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
c0e0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
c0f0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
c100: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
c110: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
c120: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
c130: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
c140: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
c150: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
c160: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
c170: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
c180: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
c190: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
c1a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
c1b0: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
c1c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
c1d0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
c1e0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
c1f0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
c200: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
c210: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
c220: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
c230: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
c240: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
c250: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
c260: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
c270: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
c280: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
c290: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
c2a0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
c2b0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
c2c0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
c2d0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
c2e0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
c2f0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
c300: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
c310: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
c320: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
c330: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
c340: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
c350: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
c360: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
c370: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
c380: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
c390: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
c3a0: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
c3b0: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
c3c0: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
c3d0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
c3e0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
c3f0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
c400: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
c410: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
c420: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
c430: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
c440: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
c450: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
c460: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
c470: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c480: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
c490: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
c4a0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
c4b0: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
c4c0: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
c4d0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
c4e0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
c4f0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
c500: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
c510: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
c520: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
c530: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
c540: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
c550: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
c560: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
c570: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
c580: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
c590: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
c5a0: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
c5b0: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
c5c0: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
c5d0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
c5e0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
c5f0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
c600: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
c610: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
c620: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
c630: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
c640: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
c650: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
c660: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
c670: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
c680: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
c690: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
c6a0: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
c6b0: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
c6c0: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
c6d0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
c6e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
c6f0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
c700: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
c710: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
c720: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
c730: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
c740: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
c750: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
c760: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
c770: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
c780: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
c790: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
c7a0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
c7b0: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
c7c0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
c7d0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
c7e0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
c7f0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
c800: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
c810: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
c820: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
c830: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
c840: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
c850: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
c860: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
c870: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
c880: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
c890: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
c8a0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
c8b0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
c8c0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
c8d0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
c8e0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
c8f0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
c900: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c910: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
c920: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c930: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
c940: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c950: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
c960: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c970: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
c980: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c990: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
c9a0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
c9b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
c9c0: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
c9d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c9e0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
c9f0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ca00: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
ca10: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
ca20: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
ca30: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
ca40: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
ca50: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
ca60: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
ca70: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
ca80: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
ca90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
caa0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
cab0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
cac0: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
cad0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
cae0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
caf0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
cb00: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
cb10: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
cb20: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
cb30: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
cb40: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
cb50: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
cb60: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
cb70: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
cb80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
cb90: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
cba0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
cbb0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
cbc0: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
cbd0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
cbe0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
cbf0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
cc00: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
cc10: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
cc20: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
cc30: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
cc40: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
cc50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
cc60: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
cc70: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
cc80: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
cc90: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
cca0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
ccb0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
ccc0: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
ccd0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
cce0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
ccf0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
cd00: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
cd10: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
cd20: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
cd30: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
cd40: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cd50: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
cd60: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
cd70: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
cd80: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
cd90: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
cda0: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
cdb0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
cdc0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
cdd0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
cde0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
cdf0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
ce00: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
ce10: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
ce20: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
ce30: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
ce40: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
ce50: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
ce60: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
ce70: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
ce80: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
ce90: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
cea0: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
ceb0: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
cec0: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
ced0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
cee0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
cef0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
cf00: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
cf10: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
cf20: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
cf30: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
cf40: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
cf50: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
cf60: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
cf70: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
cf80: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
cf90: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
cfa0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
cfb0: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
cfc0: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
cfd0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
cfe0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
cff0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
d000: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
d010: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
d020: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
d030: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
d040: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
d050: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
d060: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
d070: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
d080: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
d090: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
d0a0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
d0b0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
d0c0: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
d0d0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
d0e0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
d0f0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
d100: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
d110: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
d120: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
d130: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
d140: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
d150: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
d160: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
d170: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
d180: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
d190: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
d1a0: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
d1b0: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
d1c0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
d1d0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
d1e0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
d1f0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
d200: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
d210: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
d220: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
d230: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
d240: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
d250: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
d260: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
d270: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
d280: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
d290: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
d2a0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
d2b0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
d2c0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
d2d0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
d2e0: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
d2f0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
d300: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
d310: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
d320: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
d330: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
d340: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
d350: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
d360: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
d370: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
d380: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
d390: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
d3a0: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
d3b0: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
d3c0: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
d3d0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
d3e0: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
d3f0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
d400: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
d410: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
d420: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
d430: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
d440: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
d450: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
d460: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
d470: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
d480: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
d490: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
d4a0: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
d4b0: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
d4c0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
d4d0: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
d4e0: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
d4f0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d500: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
d510: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
d520: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
d530: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
d540: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
d550: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
d560: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
d570: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
d580: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
d590: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
d5a0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
d5b0: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
d5c0: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
d5d0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
d5e0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
d5f0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
d600: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
d610: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
d620: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
d630: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
d640: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
d650: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
d660: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
d670: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
d680: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
d690: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
d6a0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
d6b0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
d6c0: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
d6d0: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
d6e0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
d6f0: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
d700: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
d710: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
d720: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
d730: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
d740: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
d750: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
d760: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
d770: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
d780: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
d790: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
d7a0: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
d7b0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
d7c0: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
d7d0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
d7e0: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
d7f0: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
d800: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
d810: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
d820: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
d830: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
d840: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
d850: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
d860: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
d870: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
d880: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
d890: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
d8a0: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
d8b0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
d8c0: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
d8d0: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
d8e0: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
d8f0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
d900: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
d910: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
d920: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
d930: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
d940: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
d950: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
d960: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
d970: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
d980: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
d990: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
d9a0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
d9b0: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
d9c0: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
d9d0: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
d9e0: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
d9f0: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
da00: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
da10: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
da20: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
da30: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
da40: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
da50: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
da60: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
da70: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
da80: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
da90: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
daa0: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
dab0: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
dac0: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
dad0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
dae0: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
daf0: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
db00: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
db10: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
db20: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
db30: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
db40: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
db50: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
db60: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
db70: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
db80: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
db90: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
dba0: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
dbb0: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
dbc0: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
dbd0: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
dbe0: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
dbf0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
dc00: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
dc10: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
dc20: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
dc30: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
dc40: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
dc50: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
dc60: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
dc70: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
dc80: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
dc90: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
dca0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
dcb0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
dcc0: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
dcd0: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
dce0: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
dcf0: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
dd00: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
dd10: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
dd20: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
dd30: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
dd40: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
dd50: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
dd60: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
dd70: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
dd80: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
dd90: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
dda0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
ddb0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
ddc0: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
ddd0: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
dde0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
ddf0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
de00: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
de10: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
de20: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
de30: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
de40: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
de50: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
de60: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
de70: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
de80: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
de90: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
dea0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
deb0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
dec0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
ded0: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
dee0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
def0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
df00: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
df10: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
df20: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
df30: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
df40: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
df50: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
df60: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
df70: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
df80: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
df90: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
dfa0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
dfb0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
dfc0: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
dfd0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
dfe0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
dff0: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
e000: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
e010: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
e020: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
e030: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
e040: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
e050: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
e060: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
e070: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
e080: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
e090: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
e0a0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
e0b0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
e0c0: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
e0d0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
e0e0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
e0f0: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
e100: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
e110: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
e120: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
e130: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
e140: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
e150: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
e160: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
e170: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
e180: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
e190: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
e1a0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
e1b0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
e1c0: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
e1d0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
e1e0: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
e1f0: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
e200: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
e210: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
e220: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
e230: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e240: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
e250: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
e260: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
e270: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
e280: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
e290: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e2a0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
e2b0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
e2c0: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
e2d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e2e0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
e2f0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
e300: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
e310: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
e320: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
e330: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e340: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
e350: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
e360: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
e370: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
e380: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
e390: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
e3a0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
e3b0: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
e3c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e3d0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
e3e0: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
e3f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
e400: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
e410: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
e420: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
e430: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
e440: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
e450: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
e460: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
e470: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
e480: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
e490: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
e4a0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
e4b0: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
e4c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
e4d0: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
e4e0: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
e4f0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
e500: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
e510: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e520: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
e530: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
e540: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
e550: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
e560: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
e570: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
e580: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
e590: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
e5a0: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
e5b0: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
e5c0: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
e5d0: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
e5e0: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
e5f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
e600: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
e610: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
e620: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
e630: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
e640: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
e650: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
e660: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
e670: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
e680: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
e690: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e6a0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
e6b0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
e6c0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
e6d0: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
e6e0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
e6f0: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
e700: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
e710: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
e720: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
e730: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
e740: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
e750: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e760: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
e770: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
e780: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
e790: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
e7a0: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
e7b0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
e7c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e7d0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
e7e0: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
e7f0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
e800: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
e810: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
e820: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
e830: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
e840: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
e850: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
e860: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
e870: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
e880: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
e890: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
e8a0: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
e8b0: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
e8c0: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
e8d0: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
e8e0: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
e8f0: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
e900: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
e910: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
e920: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
e930: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
e940: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
e950: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
e960: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
e970: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
e980: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
e990: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
e9a0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
e9b0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
e9c0: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
e9d0: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
e9e0: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
e9f0: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
ea00: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
ea10: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
ea20: 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
ea30: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
ea40: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
ea50: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
ea60: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
ea70: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
ea80: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
ea90: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
eaa0: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
eab0: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
eac0: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
ead0: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
eae0: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
eaf0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
eb00: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
eb10: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
eb20: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
eb30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
eb40: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
eb50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
eb60: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
eb70: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
eb80: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
eb90: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
eba0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
ebb0: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
ebc0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
ebd0: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
ebe0: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
ebf0: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
ec00: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
ec10: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
ec20: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
ec30: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
ec40: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
ec50: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
ec60: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
ec70: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
ec80: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
ec90: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
eca0: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
ecb0: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
ecc0: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
ecd0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ece0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
ecf0: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
ed00: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
ed10: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
ed20: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
ed30: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
ed40: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
ed50: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
ed60: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
ed70: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
ed80: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
ed90: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
eda0: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
edb0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
edc0: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
edd0: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
ede0: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
edf0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
ee00: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
ee10: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
ee20: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
ee30: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
ee40: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
ee50: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
ee60: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
ee70: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
ee80: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
ee90: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
eea0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
eeb0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
eec0: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
eed0: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
eee0: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
eef0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
ef00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ef10: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
ef20: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
ef30: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
ef40: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
ef50: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
ef60: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
ef70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
ef80: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
ef90: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
efa0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
efb0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
efc0: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
efd0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
efe0: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
eff0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
f000: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
f010: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
f020: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
f030: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
f040: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f050: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
f060: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
f070: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f080: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
f090: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
f0a0: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
f0b0: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
f0c0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
f0d0: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
f0e0: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
f0f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f100: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
f110: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
f120: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
f130: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
f140: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
f150: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
f160: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
f170: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
f180: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
f190: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
f1a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
f1b0: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
f1c0: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
f1d0: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
f1e0: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
f1f0: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
f200: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
f210: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
f220: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
f230: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
f240: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
f250: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
f260: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
f270: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
f280: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
f290: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
f2a0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
f2b0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f2c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f2d0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
f2e0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
f2f0: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
f300: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
f310: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f320: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
f330: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
f340: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
f350: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
f360: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
f370: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
f380: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
f390: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
f3a0: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
f3b0: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
f3c0: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
f3d0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
f3e0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
f3f0: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
f400: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
f410: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
f420: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
f430: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
f440: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
f450: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
f460: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f470: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
f480: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
f490: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
f4a0: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
f4b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
f4c0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
f4d0: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
f4e0: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
f4f0: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
f500: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
f510: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
f520: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
f530: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
f540: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
f550: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
f560: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
f570: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
f580: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
f590: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
f5a0: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
f5b0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
f5c0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
f5d0: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
f5e0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
f5f0: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
f600: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
f610: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
f620: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
f630: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
f640: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
f650: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
f660: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
f670: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
f680: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
f690: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
f6a0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
f6b0: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
f6c0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
f6d0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
f6e0: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
f6f0: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
f700: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
f710: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
f720: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
f730: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
f740: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
f750: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
f760: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
f770: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
f780: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
f790: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
f7a0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
f7b0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
f7c0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f7d0: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
f7e0: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
f7f0: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
f800: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
f810: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
f820: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
f830: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
f840: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
f850: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
f860: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
f870: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
f880: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
f890: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
f8a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
f8b0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
f8c0: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
f8d0: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
f8e0: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
f8f0: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
f900: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
f910: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
f920: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
f930: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
f940: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
f950: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
f960: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
f970: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
f980: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
f990: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
f9a0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
f9b0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
f9c0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
f9d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
f9e0: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
f9f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
fa00: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
fa10: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
fa20: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
fa30: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
fa40: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
fa50: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
fa60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fa70: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
fa80: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
fa90: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
faa0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
fab0: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
fac0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
fad0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
fae0: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
faf0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
fb00: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
fb10: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
fb20: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
fb30: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
fb40: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
fb50: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
fb60: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
fb70: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
fb80: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
fb90: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
fba0: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
fbb0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
fbc0: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
fbd0: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
fbe0: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
fbf0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
fc00: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
fc10: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
fc20: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
fc30: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
fc40: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
fc50: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
fc60: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
fc70: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
fc80: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
fc90: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
fca0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
fcb0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
fcc0: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
fcd0: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
fce0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fcf0: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
fd00: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
fd10: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
fd20: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
fd30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
fd40: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
fd50: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
fd60: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
fd70: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
fd80: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
fd90: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
fda0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
fdb0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
fdc0: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
fdd0: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
fde0: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
fdf0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
fe00: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
fe10: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
fe20: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
fe30: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
fe40: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
fe50: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
fe60: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
fe70: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
fe80: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
fe90: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
fea0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
feb0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
fec0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
fed0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
fee0: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
fef0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
ff00: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
ff10: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
ff20: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
ff30: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
ff40: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
ff50: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
ff60: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
ff70: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
ff80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ff90: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
ffa0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
ffb0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
ffc0: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
ffd0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
ffe0: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
fff0: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
10000 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10010 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
10020 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
10030 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
10040 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10050 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
10060 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
10070 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
10080 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
10090 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
100a0 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
100b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
100c0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
100d0 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
100e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
100f0 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
10100 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
10110 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
10120 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
10130 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
10140 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
10150 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
10160 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10170 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
10180 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
10190 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
101a0 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
101b0 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
101c0 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
101d0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
101e0 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
101f0 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
10200 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
10210 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
10220 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
10230 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
10240 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10250 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
10260 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
10270 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
10280 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
10290 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
102a0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
102b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
102c0 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
102d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
102e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
102f0 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
10300 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10310 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
10320 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
10330 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
10340 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
10350 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
10360 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
10370 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
10380 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
10390 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
103a0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
103b0 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
103c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
103d0 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
103e0 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
103f0 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
10400 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10410 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
10420 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
10430 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
10440 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
10450 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
10460 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
10470 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
10480 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
10490 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
104a0 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
104b0 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
104c0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
104d0 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
104e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
104f0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
10500 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
10510 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
10520 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
10530 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
10540 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
10550 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
10560 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10570 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
10580 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
10590 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
105a0 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
105b0 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  essful..*/.int s
105c0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
105d0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
105e0 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
105f0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
10600 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
10610 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
10620 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
10630 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
10640 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
10650 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
10660 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
10670 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
10680 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
10690 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
106a0 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
106b0 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
106c0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
106d0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
106e0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
106f0 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
10700 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
10710 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10720 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
10730 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
10740 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
10750 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
10760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10770 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
10780 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
10790 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
107a0 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
107b0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
107c0 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
107d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
107e0 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
107f0 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
10800 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
10810 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
10820 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
10830 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
10840 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
10850 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
10860 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
10870 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
10880 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
10890 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
108a0 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
108b0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
108c0 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
108d0 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
108e0 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
108f0 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
10900 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
10910 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
10920 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
10930 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
10940 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
10950 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
10960 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
10970 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
10980 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
10990 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
109a0 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
109b0 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
109c0 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
109d0 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
109e0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
109f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
10a00 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
10a10 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
10a20 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
10a30 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
10a40 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
10a50 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
10a60 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
10a70 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
10a80 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
10a90 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46  xRealloc, and xF
10aa0 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  ree methods must
10ab0 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
10ac0 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  * malloc(), real
10ad0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
10ae0 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
10af0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
10b00 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  ibrary..** ^SQLi
10b10 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
10b20 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
10b30 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
10b40 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
10b50 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
10b60 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
10b70 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
10b80 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
10b90 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
10ba0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
10bb0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10bc0 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
10bd0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
10be0 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
10bf0 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
10c00 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
10c10 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
10c20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
10c30 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
10c40 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
10c50 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
10c60 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
10c70 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
10c80 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
10c90 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
10ca0 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
10cb0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
10cc0 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
10cd0 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
10ce0 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
10cf0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10d00 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
10d10 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
10d20 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
10d30 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
10d40 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
10d50 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
10d60 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
10d70 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
10d80 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
10d90 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
10da0 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
10db0 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
10dc0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
10dd0 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
10de0 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
10df0 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
10e00 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
10e10 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
10e20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10e30 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
10e40 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
10e50 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
10e60 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
10e70 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  or.  For example
10e80 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
10e90 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
10ea0 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
10eb0 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
10ec0 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
10ed0 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
10ee0 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
10ef0 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
10f00 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
10f10 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
10f20 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
10f30 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
10f40 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
10f50 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
10f60 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
10f70 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
10f80 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
10f90 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
10fa0 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
10fb0 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
10fc0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
10fd0 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
10fe0 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
10ff0 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
11000 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
11010 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
11020 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
11030 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
11040 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
11050 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
11060 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
11070 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
11080 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
11090 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
110a0 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
110b0 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
110c0 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
110d0 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
110e0 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
110f0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
11100 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
11110 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
11120 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11130 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
11140 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
11150 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
11160 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
11170 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
11180 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
11190 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
111a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
111b0 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
111c0 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
111d0 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
111e0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
111f0 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
11200 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
11210 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
11220 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
11230 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
11240 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
11250 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
11260 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
11270 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
11280 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
11290 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
112a0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
112b0 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
112c0 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
112d0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
112e0 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
112f0 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
11300 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
11310 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
11320 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
11330 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
11340 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
11350 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
11360 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
11370 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
11380 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
11390 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
113a0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
113b0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
113c0 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
113d0 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
113e0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
113f0 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
11400 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
11410 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
11420 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
11430 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
11440 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
11450 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
11460 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
11470 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
11480 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
11490 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
114a0 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
114b0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
114c0 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
114d0 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
114e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
114f0 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
11500 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
11510 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
11520 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
11530 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
11540 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
11550 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11560 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on}.**.** These 
11570 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
11580 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
11590 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
115a0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
115b0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
115c0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
115d0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
115e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
115f0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
11600 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
11610 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
11620 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
11630 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
11640 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
11650 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
11660 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
11670 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
11680 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
11690 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
116a0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
116b0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
116c0 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
116d0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
116e0 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
116f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11700 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
11710 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
11720 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
11730 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
11740 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
11750 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
11760 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
11770 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
11780 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
11790 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
117a0 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
117b0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
117c0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
117d0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
117e0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
117f0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
11800 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
11810 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
11820 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
11830 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
11840 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
11850 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
11860 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
11870 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
11880 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
11890 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
118a0 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
118b0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
118c0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
118d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
118e0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
118f0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11900 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11910 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
11920 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
11930 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
11940 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
11950 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
11960 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
11970 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
11980 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11990 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
119a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
119b0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
119c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
119d0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
119e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
119f0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
11a00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11a10 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20  G_MULTITHREAD]] 
11a20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11a30 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64  G_MULTITHREAD</d
11a40 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
11a50 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
11a60 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
11a70 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
11a80 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
11a90 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d  ading mode] to M
11aa0 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e  ulti-thread.  In
11ab0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
11ac0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74   disables.** mut
11ad0 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61  exing on [databa
11ae0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
11af0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
11b00 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
11b10 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
11b20 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ion is responsib
11b30 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69  le for serializi
11b40 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20  ng access to.** 
11b50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11b60 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
11b70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
11b80 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74  .  But other mut
11b90 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
11ba0 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69  led so that SQLi
11bb0 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20  te will be safe 
11bc0 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74  to use in a mult
11bd0 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e  i-threaded.** en
11be0 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e  vironment as lon
11bf0 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65  g as no two thre
11c00 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75  ads attempt to u
11c10 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b  se the same.** [
11c20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11c30 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65  ion] at the same
11c40 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69   time.  ^If SQLi
11c50 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11c60 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
11c70 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
11c80 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11c90 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
11ca0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
11cb0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
11cc0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d  ble to set the M
11cd0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
11ce0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
11cf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
11d00 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
11d10 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
11d20 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11d30 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
11d40 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11d50 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
11d60 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
11d70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11d80 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20  IG_SERIALIZED]] 
11d90 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11da0 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
11db0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
11dc0 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
11dd0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
11de0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
11df0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
11e00 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65  ding mode] to Se
11e10 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68  rialized. In oth
11e20 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f  er words, this o
11e30 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
11e40 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
11e50 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
11e60 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
11e70 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
11e80 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
11e90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11ea0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
11eb0 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
11ec0 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
11ed0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
11ee0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
11ef0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
11f00 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
11f10 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
11f20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
11f30 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
11f40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11f50 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
11f60 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
11f70 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
11f80 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
11f90 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
11fa0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
11fb0 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
11fc0 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
11fd0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
11fe0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
11ff0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
12000 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
12010 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12020 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12030 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12040 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
12050 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
12060 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
12070 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
12080 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72  e to set the Ser
12090 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
120a0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
120b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
120c0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
120d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
120e0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
120f0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
12100 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e  G_SERIALIZED con
12110 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12120 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
12130 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12140 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
12150 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
12160 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
12170 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12180 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  _MALLOC option t
12190 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
121a0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
121b0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
121c0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
121d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
121e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
121f0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
12200 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
12210 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
12220 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
12230 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12240 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
12250 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
12260 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12270 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
12280 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
12290 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
122a0 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
122b0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
122c0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
122d0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
122e0 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
122f0 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
12300 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
12310 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
12320 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12330 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12340 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12350 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
12360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12370 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12380 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  GETMALLOC option
12390 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
123a0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
123b0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
123c0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
123d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
123e0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
123f0 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  ture..** The [sq
12400 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12410 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
12420 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
12430 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
12440 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
12450 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
12460 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
12470 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
12480 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
12490 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
124a0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
124b0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
124c0 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
124d0 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
124e0 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
124f0 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
12500 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
12510 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
12520 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12530 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64  G_MEMSTATUS]] <d
12540 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12550 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
12560 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
12570 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
12580 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TUS option takes
12590 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
125a0 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a   of type int,.**
125b0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
125c0 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  a boolean, which
125d0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
125e0 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
125f0 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79  ion of.** memory
12600 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
12610 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
12620 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12630 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a   statistics are.
12640 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  ** disabled, the
12650 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
12660 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
12670 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
12680 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
12690 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
126a0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
126b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
126c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
126d0 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
126e0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
126f0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
12700 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12710 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
12720 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
12730 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12740 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
12750 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
12760 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
12770 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
12780 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
12790 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
127a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
127b0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
127c0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
127d0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
127e0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
127f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12800 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
12810 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12820 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
12830 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
12840 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12850 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  CH option specif
12860 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
12870 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  ory buffer.** th
12880 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
12890 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65  e for scratch me
128a0 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61  mory.  ^(There a
128b0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
128c0 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f  ts.** to SQLITE_
128d0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20  CONFIG_SCRATCH: 
128e0 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
128f0 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
12900 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
12910 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
12920 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
12930 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
12940 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
12950 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
12960 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
12970 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
12980 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
12990 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
129a0 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ).)^.** The firs
129b0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
129c0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
129d0 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
129e0 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
129f0 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12a00 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12a10 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f   ^SQLite will no
12a20 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20  t use more than 
12a30 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
12a40 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a  ers per thread..
12a50 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
12a60 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20  never request a 
12a70 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
12a80 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
12a90 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
12aa0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
12ab0 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  ze..** ^If SQLit
12ac0 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
12ad0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
12ae0 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
12af0 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12b00 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
12b10 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
12b20 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
12b30 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
12b40 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
12b50 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
12b60 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68  eeded.<p>.** ^Wh
12b70 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  en the applicati
12b80 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20  on provides any 
12b90 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63  amount of scratc
12ba0 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a  h memory using.*
12bb0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12bc0 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20  SCRATCH, SQLite 
12bd0 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61  avoids unnecessa
12be0 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c  ry large.** [sql
12bf0 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70  ite3_malloc|heap
12c00 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a   allocations]..*
12c10 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20  * This can help 
12c20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72  [Robson proof|pr
12c30 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  event memory all
12c40 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  ocation failures
12c50 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a  ] due to heap.**
12c60 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69   fragmentation i
12c70 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62  n low-memory emb
12c80 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a  edded systems..*
12c90 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
12ca0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12cb0 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
12cc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
12cd0 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
12ce0 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
12cf0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
12d00 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
12d10 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
12d20 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
12d30 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
12d40 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
12d50 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
12d60 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
12d70 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
12d80 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
12d90 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
12da0 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
12db0 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
12dc0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
12dd0 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
12de0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
12df0 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
12e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12e10 41 43 48 45 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67  ACHE2].** config
12e20 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a  uration option..
12e30 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
12e40 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
12e50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
12e60 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e  AGECACHE: A poin
12e70 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65  ter to.** 8-byte
12e80 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
12e90 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
12ea0 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
12eb0 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
12ec0 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
12ed0 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
12ee0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
12ef0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
12f00 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
12f10 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
12f20 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
12f30 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
12f40 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
12f50 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
12f60 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
12f70 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
12f80 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
12f90 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
12fa0 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
12fb0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
12fc0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
12fd0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
12fe0 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20  ] option .** to 
12ff0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13000 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  )]..** ^It is ha
13010 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
13020 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
13030 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
13040 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
13050 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
13060 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
13070 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
13080 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72  t should pointer
13090 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
130a0 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d  igned block of m
130b0 65 6d 6f 72 79 20 74 68 61 74 0a 2a 2a 20 69 73  emory that.** is
130c0 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
130d0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
130e0 6f 74 68 65 72 77 69 73 65 20 73 75 62 73 65 71  otherwise subseq
130f0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
13100 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
13110 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
13120 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
13130 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
13140 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
13150 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
13160 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
13170 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
13180 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
13190 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
131a0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
131b0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
131c0 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
131d0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
131e0 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
131f0 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
13200 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
13210 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
13220 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
13230 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e  rage space.</dd>
13240 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13250 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
13260 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13270 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
13280 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
13290 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
132a0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
132b0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
132c0 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
132d0 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
132e0 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
132f0 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
13300 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
13310 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
13320 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
13330 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
13340 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
13350 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13360 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  E]..** ^The SQLI
13370 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
13380 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
13390 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
133a0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  e is compiled.**
133b0 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51   with either [SQ
133c0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
133d0 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  YS3] or [SQLITE_
133e0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
133f0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  and returns.** [
13400 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13410 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69   invoked otherwi
13420 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  se..** ^There ar
13430 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13440 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
13450 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38  IG_HEAP:.** An 8
13460 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
13470 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
13480 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
13490 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
134a0 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
134b0 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
134c0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
134d0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
134e0 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
134f0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
13500 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
13510 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
13520 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
13530 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
13540 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
13550 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
13560 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
13570 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
13580 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
13590 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
135a0 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
135b0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
135c0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  er is not NULL t
135d0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
135e0 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
135f0 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
13600 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
13610 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
13620 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
13630 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
13640 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
13650 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
13660 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
13670 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
13680 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
13690 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
136a0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
136b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
136c0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
136d0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
136e0 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
136f0 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
13700 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
13710 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13720 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
13730 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
13740 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13750 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
13760 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13770 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
13780 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13790 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74  CONFIG_MUTEX opt
137a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
137b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
137c0 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  h is a.** pointe
137d0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
137e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
137f0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
13800 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
13810 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
13820 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65  fies alternative
13830 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
13840 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
13850 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65  used.** in place
13860 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
13870 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
13880 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
13890 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
138a0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
138b0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
138c0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
138d0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
138e0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
138f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13900 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
13910 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13920 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13930 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13940 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13950 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13960 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13970 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
13980 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
13990 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
139a0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
139b0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
139c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
139d0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
139e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
139f0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
13a00 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
13a10 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13a20 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
13a30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13a40 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
13a50 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
13a60 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
13a70 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
13a80 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13a90 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
13aa0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13ab0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
13ac0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13ad0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13ae0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13af0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
13b00 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
13b10 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
13b20 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
13b30 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
13b40 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
13b50 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
13b60 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
13b70 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
13b80 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
13b90 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
13ba0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
13bb0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
13bc0 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
13bd0 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
13be0 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
13bf0 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
13c00 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
13c10 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
13c20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13c30 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13c40 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13c50 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13c60 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13c70 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13c80 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13c90 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13ca0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
13cb0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
13cc0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
13cd0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13ce0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
13cf0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
13d00 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13d10 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
13d20 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
13d30 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
13d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13d50 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
13d60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13d70 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
13d80 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13d90 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13da0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
13db0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
13dc0 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
13dd0 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f  e default size o
13de0 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
13df0 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61  ry on each [data
13e00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13e10 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
13e20 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
13e30 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
13e40 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
13e50 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
13e60 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
13e70 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
13e80 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
13e90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13ea0 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45  ion.)^  ^(SQLITE
13eb0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13ec0 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69  E.** sets the <i
13ed0 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
13ee0 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
13ef0 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
13f00 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
13f10 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74  option to [sqlit
13f20 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
13f30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
13f40 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
13f50 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
13f60 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
13f70 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
13f80 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
13f90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13fa0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
13fb0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13fc0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
13fd0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
13fe0 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
13ff0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14000 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14010 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
14020 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14030 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14040 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
14050 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a  bject specifies.
14060 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ** the interface
14070 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
14080 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
14090 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51  tation.)^.** ^SQ
140a0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
140b0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
140c0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
140d0 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  2] object.</dd>.
140e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
140f0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14100 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14110 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
14120 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14130 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14140 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69  _GETPCACHE2 opti
14150 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14160 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14170 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
14180 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14190 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
141a0 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
141b0 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68   copies of.** th
141c0 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63  e current page c
141d0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
141e0 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
141f0 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
14200 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14210 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
14220 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
14230 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
14240 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
14250 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
14260 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
14270 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
14280 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
14290 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
142a0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
142b0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
142c0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
142d0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
142e0 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
142f0 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
14300 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
14310 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
14320 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
14330 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
14340 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
14350 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
14360 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
14370 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
14380 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
14390 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
143a0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
143b0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
143c0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
143d0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
143e0 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
143f0 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
14400 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
14410 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
14420 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
14430 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
14440 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
14450 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
14460 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
14470 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14480 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
14490 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
144a0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
144b0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
144c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
144d0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
144e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
144f0 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
14500 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
14510 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
14520 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
14530 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
14540 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
14550 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
14560 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
14570 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
14580 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
14590 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
145a0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
145b0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
145c0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
145d0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
145e0 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
145f0 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
14600 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
14610 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
14620 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
14630 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
14640 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
14650 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
14660 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
14670 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
14680 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
14690 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
146a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
146b0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
146c0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
146d0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
146e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
146f0 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
14700 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
14710 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  dd>^(The SQLITE_
14720 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f  CONFIG_URI optio
14730 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14740 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
14750 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e  e int..** If non
14760 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20  -zero, then URI 
14770 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
14780 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
14790 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
147a0 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  s zero,.** then 
147b0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
147c0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
147d0 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
147e0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
147f0 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c  y.** enabled, al
14800 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73  l filenames pass
14810 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
14820 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
14830 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20  _open_v2()],.** 
14840 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
14850 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
14860 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
14870 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
14880 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
14890 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
148a0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
148b0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
148c0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
148d0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
148e0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
148f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
14900 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
14910 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
14920 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
14930 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
14940 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
14950 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
14960 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
14970 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
14980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14990 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
149a0 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
149b0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
149c0 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
149d0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
149e0 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
149f0 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
14a00 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
14a10 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
14a20 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
14a30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14a40 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14a50 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
14a60 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
14a70 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
14a80 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
14a90 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
14aa0 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69  _INDEX_SCAN opti
14ab0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14ac0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67  e integer.** arg
14ad0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
14ae0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
14af0 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
14b00 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
14b10 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65  sable.** the use
14b20 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
14b30 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
14b40 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
14b50 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
14b60 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
14b70 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
14b80 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
14b90 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
14ba0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14bb0 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
14bc0 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
14bd0 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
14be0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14bf0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
14c00 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
14c10 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
14c20 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
14c30 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
14c40 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
14c50 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
14c60 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
14c70 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
14c80 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
14c90 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
14ca0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
14cb0 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
14cc0 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
14cd0 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
14ce0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
14cf0 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
14d00 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
14d10 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
14d20 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
14d30 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
14d40 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
14d50 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
14d60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14d70 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
14d80 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14d90 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14da0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
14db0 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
14dc0 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
14dd0 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
14de0 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
14df0 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
14e00 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
14e10 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
14e20 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
14e30 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
14e40 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
14e50 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
14e60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14e70 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
14e80 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
14e90 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
14ea0 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
14eb0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
14ec0 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
14ed0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
14ee0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
14ef0 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
14f00 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
14f10 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
14f20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
14f30 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
14f40 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
14f50 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
14f60 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
14f70 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
14f80 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
14f90 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
14fa0 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
14fb0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
14fc0 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
14fd0 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
14fe0 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
14ff0 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
15000 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
15010 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
15020 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
15030 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15040 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
15050 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
15060 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
15070 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
15080 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
15090 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
150a0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
150b0 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
150c0 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
150d0 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
150e0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
150f0 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
15100 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
15110 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
15120 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
15130 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
15140 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
15150 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
15160 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
15170 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
15180 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
15190 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
151a0 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
151b0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
151c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
151d0 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
151e0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
151f0 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
15200 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
15210 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
15220 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
15230 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15240 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
15250 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
15260 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
15270 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
15280 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
15290 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
152a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
152b0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
152c0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
152d0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
152e0 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
152f0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
15300 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
15310 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
15320 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
15330 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
15340 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
15350 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
15360 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
15370 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
15380 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
15390 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
153a0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
153b0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
153c0 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
153d0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
153e0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
153f0 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
15400 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
15410 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
15420 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
15430 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
15440 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
15450 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
15460 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
15470 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
15480 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69  ze.** will be si
15490 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
154a0 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f   if necessary so
154b0 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
154c0 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  t exceed the.** 
154d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
154e0 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
154f0 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
15500 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
15510 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
15520 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
15530 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
15540 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
15550 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
15560 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
15570 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
15580 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
15590 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
155a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
155b0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
155c0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
155d0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
155e0 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
155f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15600 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
15610 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
15620 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
15630 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
15640 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69  d for Windows wi
15650 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
15660 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
15670 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
15680 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51  .** defined. ^SQ
15690 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
156a0 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
156b0 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
156c0 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
156d0 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
156e0 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
156f0 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
15700 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b  ed heap..**.** [
15710 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15720 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a  CACHE_HDRSZ]].**
15730 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15740 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a  IG_PCACHE_HDRSZ.
15750 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15760 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15770 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _HDRSZ option ta
15780 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
15790 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
157a0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
157b0 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77  an integer and w
157c0 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20  rites into that 
157d0 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62  integer the numb
157e0 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62  er of extra.** b
157f0 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65  ytes per page re
15800 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20  quired for each 
15810 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f  page in [SQLITE_
15820 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15830 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74  ]..** The amount
15840 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20   of extra space 
15850 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61  required can cha
15860 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  nge depending on
15870 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a   the compiler,.*
15880 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72  * target platfor
15890 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65  m, and SQLite ve
158a0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rsion..**.** [[S
158b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
158c0 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
158d0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a  TE_CONFIG_PMASZ.
158e0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
158f0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
15900 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15910 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
15920 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75  which.** is an u
15930 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
15940 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69  and sets the "Mi
15950 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20  nimum PMA Size" 
15960 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72  for the multithr
15970 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20  eaded.** sorter 
15980 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  to that integer.
15990 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69    The default mi
159a0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69  nimum PMA Size i
159b0 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  s set by the.** 
159c0 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50  [SQLITE_SORTER_P
159d0 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  MASZ] compile-ti
159e0 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20  me option.  New 
159f0 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e  threads are laun
15a00 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20  ched.** to help 
15a10 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74  with sort operat
15a20 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74  ions when multit
15a30 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a  hreaded sorting.
15a40 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75  ** is enabled (u
15a50 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  sing the [PRAGMA
15a60 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e   threads] comman
15a70 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e  d) and the amoun
15a80 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20  t of content.** 
15a90 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63  to be sorted exc
15aa0 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69  eeds the page si
15ab0 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e  ze times the min
15ac0 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  imum of the.** [
15ad0 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a  PRAGMA cache_siz
15ae0 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74  e] setting and t
15af0 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f  his value..** </
15b00 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
15b10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
15b20 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
15b30 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
15b40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15b50 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
15b60 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
15b70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
15b80 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
15b90 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15ba0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15bb0 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
15bc0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
15bd0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
15be0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15bf0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
15c00 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
15c10 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
15c20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15c30 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
15c40 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
15c50 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
15c60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15c70 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
15c80 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
15c90 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
15ca0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15cb0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
15cc0 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
15cd0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
15ce0 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
15cf0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15d00 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
15d10 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
15d20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15d30 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
15d40 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
15d50 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
15d60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15d70 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
15d80 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
15d90 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15da0 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
15db0 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
15dc0 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
15dd0 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
15de0 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
15df0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15e00 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
15e10 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
15e20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15e30 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
15e40 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   14  /* no-op */
15e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15e60 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15e70 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70      15  /* no-op
15e80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15e90 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
15ea0 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
15eb0 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
15ec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15ed0 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
15ee0 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   17  /* int */.#
15ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15f00 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20  NFIG_PCACHE2    
15f10 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33    18  /* sqlite3
15f20 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
15f30 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15f40 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15f50 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73  ACHE2   19  /* s
15f60 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
15f70 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
15f80 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15f90 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
15fa0 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20  SCAN 20  /* int 
15fb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15fc0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20  E_CONFIG_SQLLOG 
15fd0 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71        21  /* xSq
15fe0 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  llog, void* */.#
15ff0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16000 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  NFIG_MMAP_SIZE  
16010 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33    22  /* sqlite3
16020 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f  _int64, sqlite3_
16030 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65  int64 */.#define
16040 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
16050 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20  IN32_HEAPSIZE   
16060 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42     23  /* int nB
16070 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  yte */.#define S
16080 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16090 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20  CHE_HDRSZ       
160a0 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a   24  /* int *psz
160b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
160c0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
160d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
160e0 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e    /* unsigned in
160f0 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a  t szPma */../*.*
16100 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
16110 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
16120 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
16130 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
16140 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
16150 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
16160 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
16170 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
16180 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
16190 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
161a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
161b0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
161c0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
161d0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
161e0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
161f0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
16200 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
16210 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
16220 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
16230 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
16240 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
16250 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
16260 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
16270 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
16280 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
16290 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
162a0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
162b0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
162c0 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
162d0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
162e0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
162f0 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
16300 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
16310 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
16320 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
16330 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
16340 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
16350 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
16360 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
16370 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
16380 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
16390 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
163a0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
163b0 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
163c0 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
163d0 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
163e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
163f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
16400 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
16410 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
16420 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
16430 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
16440 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
16450 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16460 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
16470 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
16480 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
16490 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
164a0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
164b0 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
164c0 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
164d0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
164e0 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
164f0 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
16500 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
16510 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
16520 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
16530 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
16540 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
16550 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16560 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
16570 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
16580 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
16590 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
165a0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
165b0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
165c0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
165d0 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
165e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
165f0 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
16600 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
16610 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
16620 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
16630 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
16640 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
16650 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
16660 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
16670 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
16680 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
16690 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
166a0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
166b0 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
166c0 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
166d0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
166e0 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
166f0 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
16700 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
16710 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
16720 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
16730 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
16740 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16750 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
16760 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
16770 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
16780 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
16790 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
167a0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
167b0 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
167c0 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
167d0 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
167e0 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
167f0 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
16800 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16810 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
16820 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
16830 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
16840 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
16850 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
16860 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
16870 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
16880 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
16890 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
168a0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
168b0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
168c0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
168d0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
168e0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
168f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16900 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16910 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
16920 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
16930 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
16940 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
16950 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
16960 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
16970 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
16980 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
16990 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
169a0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
169b0 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
169c0 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
169d0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
169e0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
169f0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
16a00 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
16a10 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
16a20 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16a30 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
16a40 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
16a50 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
16a60 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
16a70 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
16a80 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
16a90 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
16aa0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
16ab0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
16ac0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16ad0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
16ae0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
16af0 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
16b00 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
16b10 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
16b20 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
16b30 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
16b40 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16b50 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
16b60 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
16b70 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
16b80 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
16b90 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
16ba0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
16bb0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16bc0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16bd0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16be0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16bf0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
16c00 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16c10 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
16c20 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
16c30 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
16c40 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
16c50 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
16c60 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
16c70 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16c80 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16c90 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
16ca0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
16cb0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
16cc0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
16cd0 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
16ce0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
16cf0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
16d00 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
16d10 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
16d20 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
16d30 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
16d40 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
16d50 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
16d60 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
16d70 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
16d80 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
16d90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16da0 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
16db0 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
16dc0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16dd0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16de0 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
16df0 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
16e00 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16e10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16e20 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
16e30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
16e40 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
16e50 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
16e60 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
16e70 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
16e80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
16e90 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
16ea0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
16eb0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
16ec0 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
16ed0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
16ee0 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
16ef0 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
16f00 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
16f10 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
16f20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
16f30 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
16f40 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
16f50 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
16f60 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
16f70 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
16f80 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
16f90 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
16fa0 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
16fb0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
16fc0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
16fd0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
16fe0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
16ff0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
17000 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
17010 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
17020 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
17030 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
17040 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
17050 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
17060 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
17070 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
17080 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
17090 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
170a0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
170b0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
170c0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
170d0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
170e0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
170f0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
17100 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
17110 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
17120 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
17130 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
17140 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
17150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17160 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17170 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
17180 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
17190 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
171a0 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
171b0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
171c0 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
171d0 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
171e0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
171f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17200 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
17210 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
17220 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
17230 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
17240 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
17250 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
17260 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
17270 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
17280 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
17290 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
172a0 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
172b0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
172c0 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
172d0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
172e0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
172f0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
17300 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
17310 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
17320 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
17330 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
17340 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
17350 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
17360 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
17370 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
17380 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17390 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
173a0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
173b0 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
173c0 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
173d0 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
173e0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
173f0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
17400 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
17410 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
17420 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
17430 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
17440 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
17450 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
17460 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
17470 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
17480 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
17490 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
174a0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
174b0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
174c0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
174d0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
174e0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
174f0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
17500 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
17510 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
17520 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
17530 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
17540 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
17550 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
17560 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
17570 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
17580 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
17590 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
175a0 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
175b0 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
175c0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
175d0 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
175e0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
175f0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
17600 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
17610 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
17620 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
17630 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
17640 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
17650 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
17660 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
17670 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
17680 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
17690 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
176a0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
176b0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
176c0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
176d0 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
176e0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
176f0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
17700 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
17710 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
17720 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
17730 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
17740 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
17750 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
17760 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
17770 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17780 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17790 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
177a0 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
177b0 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
177c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
177d0 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
177e0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
177f0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
17800 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
17810 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
17820 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
17830 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
17840 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17850 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
17860 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17870 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
17880 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
17890 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
178a0 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
178b0 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
178c0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
178d0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
178e0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
178f0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
17900 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17910 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
17920 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
17930 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
17940 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17950 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
17960 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c  f rows modified,
17970 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20   inserted or.** 
17980 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
17990 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
179a0 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
179b0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a  PDATE or DELETE.
179c0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20  ** statement on 
179d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
179e0 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  nection specifie
179f0 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61  d by the only pa
17a00 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65  rameter..** ^Exe
17a10 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
17a20 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
17a30 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
17a40 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65  modify the value
17a50 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
17a60 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
17a70 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67  *.** ^Only chang
17a80 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79  es made directly
17a90 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20   by the INSERT, 
17aa0 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
17ab0 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a   statement are.*
17ac0 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61  * considered - a
17ad0 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
17ae0 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41   caused by [CREA
17af0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
17b00 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72  ggers], .** [for
17b10 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
17b20 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63  ] or [REPLACE] c
17b30 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
17b40 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75  tion are not cou
17b50 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61  nted..** .** Cha
17b60 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
17b70 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
17b80 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54  ted by .** [INST
17b90 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c  EAD OF trigger |
17ba0 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
17bb0 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  gers] are not co
17bc0 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75  unted. ^The valu
17bd0 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  e .** returned b
17be0 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
17bf0 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  s() immediately 
17c00 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c  after an INSERT,
17c10 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44   UPDATE or .** D
17c20 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
17c30 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73  run on a view is
17c40 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e   always zero. On
17c50 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
17c60 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c  to real .** tabl
17c70 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17c80 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65  **.** Things are
17c90 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65   more complicate
17ca0 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33  d if the sqlite3
17cb0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
17cc0 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74  ion is.** execut
17cd0 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67  ed while a trigg
17ce0 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75  er program is ru
17cf0 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20  nning. This may 
17d00 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a  happen if the.**
17d10 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68   program uses th
17d20 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
17d30 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69   function], or i
17d40 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c  f some other cal
17d50 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
17d60 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65  n invokes sqlite
17d70 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65  3_changes() dire
17d80 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c  ctly. Essentiall
17d90 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y:.** .** <ul>.*
17da0 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72  *   <li> ^(Befor
17db0 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69  e entering a tri
17dc0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65  gger program the
17dd0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
17de0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c  by.**        sql
17df0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
17e00 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64  unction is saved
17e10 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67  . After the trig
17e20 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20  ger program .** 
17e30 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73         has finis
17e40 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61  hed, the origina
17e50 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f  l value is resto
17e60 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20  red.)^.** .**   
17e70 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20  <li> ^(Within a 
17e80 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
17e90 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44  each INSERT, UPD
17ea0 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a  ATE and DELETE .
17eb0 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d  **        statem
17ec0 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c  ent sets the val
17ed0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
17ee0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17ef0 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e   .**        upon
17f00 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e   completion as n
17f10 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65  ormal. Of course
17f20 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c  , this value wil
17f30 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a  l not include .*
17f40 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61  *        any cha
17f50 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62  nges performed b
17f60 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20  y sub-triggers, 
17f70 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  as the sqlite3_c
17f80 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
17f90 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62      value will b
17fa0 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74  e saved and rest
17fb0 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20  ored after each 
17fc0 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20  sub-trigger has 
17fd0 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  run.)^.** </ul>.
17fe0 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61  ** .** ^This mea
17ff0 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63  ns that if the c
18000 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
18010 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61  ction (or simila
18020 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79  r) is used.** by
18030 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52   the first INSER
18040 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
18050 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
18060 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
18070 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  it .** returns t
18080 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20  he value as set 
18090 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67  when the calling
180a0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e   statement began
180b0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
180c0 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79  If it is used by
180d0 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73   the second or s
180e0 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73  ubsequent such s
180f0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
18100 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72  a trigger .** pr
18110 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65  ogram, the value
18120 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63   returned reflec
18130 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ts the number of
18140 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62   rows modified b
18150 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f  y the .** previo
18160 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  us INSERT, UPDAT
18170 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
18180 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
18190 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
181a0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
181b0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
181c0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
181d0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
181e0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
181f0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
18200 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
18210 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
18220 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
18230 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
18240 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
18250 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18260 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
18270 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
18280 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
18290 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
182a0 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
182b0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
182c0 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
182d0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
182e0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
182f0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
18300 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
18310 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
18320 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
18330 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
18340 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
18350 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
18360 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
18370 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
18380 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
18390 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
183a0 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
183b0 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
183c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
183d0 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
183e0 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
183f0 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
18400 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
18410 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
18420 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
18430 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
18440 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
18450 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18460 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
18470 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
18480 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
18490 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
184a0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
184b0 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
184c0 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
184d0 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
184e0 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
184f0 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
18500 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
18510 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
18520 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
18530 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
18540 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
18550 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
18560 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
18570 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
18580 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18590 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
185a0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
185b0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
185c0 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
185d0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
185e0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
185f0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
18600 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
18610 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
18620 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
18630 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
18640 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
18650 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
18660 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
18670 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
18680 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
18690 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
186a0 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
186b0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
186c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
186d0 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
186e0 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
186f0 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
18700 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
18710 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
18720 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
18730 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
18740 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
18750 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
18760 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
18770 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
18780 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
18790 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
187a0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
187b0 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
187c0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
187d0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
187e0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
187f0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
18800 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
18810 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
18820 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
18830 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
18840 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
18850 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
18860 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
18870 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
18880 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
18890 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
188a0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
188b0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
188c0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
188d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
188e0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
188f0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
18900 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
18910 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
18920 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
18930 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
18940 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
18950 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
18960 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
18970 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
18980 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
18990 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
189a0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
189b0 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
189c0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
189d0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
189e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
189f0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
18a00 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
18a10 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
18a20 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
18a30 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
18a40 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
18a50 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
18a60 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
18a70 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
18a80 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
18a90 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
18aa0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
18ab0 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
18ac0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
18ad0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
18ae0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
18af0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
18b00 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
18b10 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
18b20 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
18b30 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
18b40 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
18b50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
18b60 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
18b70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
18b80 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
18b90 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
18ba0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18bb0 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
18bc0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
18bd0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
18be0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
18bf0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
18c00 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
18c10 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
18c20 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
18c30 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
18c40 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
18c50 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
18c60 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
18c70 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
18c80 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
18c90 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
18ca0 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
18cb0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18cc0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
18cd0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
18ce0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
18cf0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
18d00 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
18d10 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
18d20 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
18d30 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
18d40 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
18d50 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
18d60 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
18d70 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18d80 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
18d90 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
18da0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18db0 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
18dc0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
18dd0 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
18de0 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
18df0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
18e00 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
18e10 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18e20 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
18e30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
18e40 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
18e50 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
18e60 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
18e70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
18e80 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
18e90 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
18ea0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
18eb0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
18ec0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
18ed0 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
18ee0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
18ef0 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
18f00 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
18f10 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
18f20 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
18f30 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
18f40 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
18f50 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
18f60 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
18f70 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
18f80 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
18f90 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
18fa0 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
18fb0 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
18fc0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
18fd0 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
18fe0 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
18ff0 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
19000 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
19010 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
19020 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
19030 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
19040 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
19050 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
19060 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
19070 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
19080 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
19090 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
190a0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
190b0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
190c0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
190d0 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
190e0 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
190f0 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
19100 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
19110 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
19120 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
19130 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
19140 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
19150 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
19160 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
19170 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
19180 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
19190 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
191a0 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
191b0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
191c0 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
191d0 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
191e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
191f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
19200 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
19210 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
19220 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
19230 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
19240 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
19250 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
19260 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
19270 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
19280 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
19290 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
192a0 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
192b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
192c0 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
192d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
192e0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
192f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
19300 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
19310 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
19320 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
19330 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
19340 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
19350 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
19360 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
19370 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
19380 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
19390 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
193a0 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
193b0 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
193c0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
193d0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
193e0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
193f0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
19400 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
19410 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
19420 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19430 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
19440 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
19450 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
19460 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
19470 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
19480 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
19490 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
194a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
194b0 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
194c0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
194d0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
194e0 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
194f0 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
19500 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45  USY Errors.** KE
19510 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61  YWORDS: {busy-ha
19520 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20  ndler callback} 
19530 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a  {busy handler}.*
19540 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19550 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
19560 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
19570 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
19580 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
19590 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
195a0 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
195b0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
195c0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
195d0 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
195e0 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
195f0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
19600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19610 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
19620 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
19630 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
19640 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
19650 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
19660 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
19670 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
19680 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
19690 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
196a0 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
196b0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
196c0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
196d0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
196e0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
196f0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
19700 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
19710 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
19720 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
19730 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
19740 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
19750 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
19760 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
19770 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
19780 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
19790 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
197a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
197b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
197c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
197d0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
197e0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
197f0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
19800 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19810 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
19820 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
19830 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
19840 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
19850 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
19860 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
19870 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
19880 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72   been invoked pr
19890 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65  eviously for the
198a0 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
198b0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
198c0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
198d0 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
198e0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
198f0 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
19900 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
19910 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
19920 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65  LITE_BUSY] is re
19930 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65  turned.** to the
19940 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
19950 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
19960 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
19970 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
19980 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
19990 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68  ade to access th
199a0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
199b0 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
199c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
199d0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
199e0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
199f0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
19a00 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
19a10 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
19a20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
19a30 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
19a40 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
19a50 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
19a60 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
19a70 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
19a80 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
19a90 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
19aa0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
19ab0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  ].** to the appl
19ac0 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20  ication instead 
19ad0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
19ae0 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
19af0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
19b00 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
19b10 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
19b20 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
19b30 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
19b40 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
19b50 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
19b60 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
19b70 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
19b80 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
19b90 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
19ba0 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
19bb0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
19bc0 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
19bd0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
19be0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
19bf0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
19c00 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
19c10 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
19c20 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
19c30 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
19c40 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
19c50 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
19c60 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
19c70 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
19c80 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19c90 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
19ca0 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
19cb0 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
19cc0 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
19cd0 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
19ce0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
19cf0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
19d00 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
19d10 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
19d20 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
19d30 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
19d40 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
19d50 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
19d60 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
19d70 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
19d80 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
19d90 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s NULL..**.** ^(
19da0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
19db0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
19dc0 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
19dd0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
19de0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19df0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
19e00 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
19e10 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
19e20 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
19e30 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
19e40 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
19e50 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
19e60 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61  ()].** or evalua
19e70 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73  ting [PRAGMA bus
19e80 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c  y_timeout=N] wil
19e90 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  l change the.** 
19ea0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64  busy handler and
19eb0 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20   thus clear any 
19ec0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62  previously set b
19ed0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
19ee0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
19ef0 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
19f00 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
19f10 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
19f20 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
19f30 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
19f40 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
19f50 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65  andler.  In othe
19f60 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20  r words,.** the 
19f70 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
19f80 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20  not reentrant.  
19f90 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
19fa0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
19fb0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
19fc0 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
19fd0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
19fe0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
19ff0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1a000 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1a010 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1a020 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1a030 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20  handler..*/.int 
1a040 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1a050 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1a060 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
1a070 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1a080 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1a090 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1a0a0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1a0b0 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1a0c0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1a0d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1a0e0 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1a0f0 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1a100 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1a110 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1a120 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1a130 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1a140 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1a150 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1a160 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1a170 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1a180 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1a190 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1a1a0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1a1b0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1a1c0 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1a1d0 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1a1e0 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1a1f0 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1a200 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1a210 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1a220 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1a230 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1a240 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1a250 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1a260 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1a270 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1a280 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1a290 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1a2a0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1a2b0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1a2c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a2d0 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1a2e0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1a2f0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1a300 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1a310 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1a320 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a330 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1a340 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1a350 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1a360 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1a370 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1a380 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1a390 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1a3a0 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  out].*/.int sqli
1a3b0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1a3c0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
1a3d0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
1a3e0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
1a3f0 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
1a400 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
1a410 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1a420 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1a430 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1a440 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1a450 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1a460 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1a470 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1a480 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1a490 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1a4a0 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1a4b0 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1a4c0 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1a4d0 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1a4e0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a4f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1a500 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1a510 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1a520 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1a530 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1a540 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1a550 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1a560 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1a570 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1a580 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1a590 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1a5a0 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1a5b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1a5c0 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1a5d0 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1a5e0 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1a5f0 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1a600 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1a610 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1a620 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1a630 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1a640 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1a650 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1a660 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1a670 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1a680 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1a690 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1a6a0 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1a6b0 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1a6c0 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1a6d0 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1a6e0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1a6f0 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1a700 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1a710 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1a720 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1a730 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1a740 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1a750 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1a760 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1a770 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1a780 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1a790 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1a7a0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1a7b0 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1a7c0 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1a7d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1a7e0 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1a7f0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1a800 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1a810 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1a820 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1a830 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1a840 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1a850 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1a860 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1a870 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1a880 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1a890 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1a8a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1a8b0 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1a8c0 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1a8d0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1a8e0 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1a8f0 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1a900 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1a910 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1a920 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a930 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1a940 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1a950 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1a960 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1a970 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1a980 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1a990 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1a9a0 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1a9b0 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1a9c0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1a9d0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1a9e0 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1a9f0 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1aa00 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1aa10 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1aa20 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1aa30 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1aa40 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1aa50 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1aa60 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1aa70 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1aa80 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1aa90 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1aaa0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1aab0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1aac0 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1aad0 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1aae0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1aaf0 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1ab00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1ab10 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1ab20 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1ab30 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1ab40 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1ab50 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1ab60 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1ab70 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1ab80 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1ab90 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1aba0 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1abb0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1abc0 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1abd0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1abe0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1abf0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1ac00 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1ac10 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1ac20 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1ac30 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1ac40 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1ac50 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1ac60 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1ac70 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1ac80 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1ac90 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1aca0 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1acb0 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1acc0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1acd0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1ace0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1acf0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1ad00 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1ad10 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ad20 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1ad30 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1ad40 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1ad50 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1ad60 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1ad70 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1ad80 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1ad90 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1ada0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1adb0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1adc0 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1add0 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1ade0 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1adf0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1ae00 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1ae10 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1ae20 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1ae30 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1ae40 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1ae50 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1ae60 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1ae70 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1ae80 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1ae90 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1aea0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1aeb0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1aec0 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1aed0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1aee0 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1aef0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1af00 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1af10 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1af20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1af30 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1af40 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1af50 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1af60 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1af70 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1af80 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1af90 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1afa0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1afb0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1afc0 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1afd0 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1afe0 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1aff0 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1b000 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1b010 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1b020 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1b030 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1b040 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1b050 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1b060 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1b070 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1b080 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1b090 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1b0a0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1b0b0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1b0c0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1b0d0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1b0e0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1b0f0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1b100 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1b110 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1b120 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1b130 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1b140 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1b150 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1b160 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1b170 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1b180 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1b190 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1b1a0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1b1b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1b1c0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1b1d0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1b1e0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1b1f0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1b200 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1b210 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b220 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1b230 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1b240 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1b250 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1b260 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1b270 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1b280 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1b290 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1b2a0 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1b2b0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1b2c0 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1b2d0 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1b2e0 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1b2f0 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1b300 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1b310 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1b320 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1b330 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1b340 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1b350 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1b360 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1b370 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1b380 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1b390 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1b3a0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1b3b0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1b3c0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1b3d0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1b3e0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1b3f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1b400 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1b410 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1b420 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1b430 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1b440 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1b450 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1b460 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1b470 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1b480 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1b490 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1b4a0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1b4b0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1b4c0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1b4d0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1b4e0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1b4f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1b500 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1b510 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1b520 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1b530 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1b540 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1b550 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1b560 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1b570 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1b580 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1b590 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1b5a0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1b5b0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1b5c0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1b5d0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1b5e0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1b5f0 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1b600 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1b610 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1b620 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1b630 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1b640 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1b650 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1b660 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1b670 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1b680 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1b690 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1b6a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1b6b0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1b6c0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1b6d0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1b6e0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1b6f0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1b700 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1b710 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1b720 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1b730 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1b740 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1b750 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1b760 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1b770 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1b780 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1b790 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1b7a0 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1b7b0 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1b7c0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1b7d0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1b7e0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1b7f0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1b800 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1b810 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1b820 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1b830 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1b840 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1b850 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1b860 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1b870 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1b880 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1b890 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1b8a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1b8b0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1b8c0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1b8d0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1b8e0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1b8f0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1b900 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1b910 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1b920 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1b930 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1b940 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b950 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1b960 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1b970 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1b980 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1b990 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1b9a0 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1b9b0 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1b9c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1b9d0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1b9e0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1b9f0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1ba00 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1ba10 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1ba20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1ba30 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1ba40 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1ba50 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1ba60 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1ba70 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1ba80 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1ba90 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1baa0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1bab0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1bac0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1bad0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1bae0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1baf0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1bb00 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1bb10 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1bb20 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1bb30 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1bb40 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1bb50 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1bb60 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1bb70 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1bb80 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1bb90 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1bba0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1bbb0 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1bbc0 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1bbd0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1bbe0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1bbf0 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1bc00 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1bc10 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1bc20 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1bc30 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1bc40 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1bc50 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1bc60 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1bc70 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1bc80 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1bc90 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1bca0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1bcb0 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1bcc0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1bcd0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1bce0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1bcf0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1bd00 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1bd10 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1bd20 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1bd30 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1bd40 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1bd50 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1bd60 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1bd70 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1bd80 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1bd90 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1bda0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1bdb0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1bdc0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1bdd0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1bde0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1bdf0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1be00 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1be10 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1be20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1be30 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1be40 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1be50 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1be60 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1be70 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1be80 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1be90 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1bea0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1beb0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1bec0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1bed0 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1bee0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1bef0 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1bf00 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1bf10 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1bf20 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1bf30 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1bf40 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1bf50 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1bf60 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1bf70 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1bf80 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1bf90 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1bfa0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1bfb0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1bfc0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1bfd0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1bfe0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1bff0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1c000 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1c010 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1c020 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1c030 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1c040 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1c050 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1c060 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1c070 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1c080 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c090 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1c0a0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1c0b0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1c0c0 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1c0d0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1c0e0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1c0f0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1c100 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1c110 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1c120 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c130 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1c140 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1c150 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1c160 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1c170 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1c180 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1c190 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1c1a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1c1b0 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
1c1c0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1c1d0 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
1c1e0 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
1c1f0 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
1c200 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
1c210 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
1c220 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
1c230 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
1c240 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
1c250 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1c260 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1c270 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
1c280 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
1c290 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1c2a0 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
1c2b0 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
1c2c0 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
1c2d0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
1c2e0 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
1c2f0 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
1c300 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
1c310 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1c320 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1c330 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1c340 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1c350 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1c360 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1c370 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1c380 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1c390 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1c3a0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1c3b0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1c3c0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1c3d0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1c3e0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1c3f0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1c400 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1c410 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1c420 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1c430 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1c440 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1c450 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1c460 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1c470 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1c480 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1c490 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1c4a0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1c4b0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1c4c0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1c4d0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1c4e0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1c4f0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1c500 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1c510 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1c520 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1c530 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1c540 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1c550 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1c560 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1c570 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1c580 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1c590 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1c5a0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1c5b0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1c5c0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1c5d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c5e0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1c5f0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1c600 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1c610 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1c620 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1c630 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1c640 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1c650 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1c660 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1c670 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1c680 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1c690 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1c6a0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1c6b0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1c6c0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1c6d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1c6e0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1c6f0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1c700 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1c710 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1c720 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1c730 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1c740 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1c750 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1c760 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1c770 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1c780 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1c790 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1c7a0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1c7b0 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1c7c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1c7d0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1c7e0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1c7f0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1c800 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1c810 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1c820 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c830 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1c840 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1c850 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1c860 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1c870 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1c880 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1c890 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1c8a0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1c8b0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1c8c0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1c8d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1c8e0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1c8f0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1c900 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1c910 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1c920 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1c930 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1c940 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1c950 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1c960 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1c970 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1c980 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1c990 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1c9a0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1c9b0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1c9c0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1c9d0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1c9e0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1c9f0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1ca00 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1ca10 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1ca20 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1ca30 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1ca40 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1ca50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1ca60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ca70 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1ca80 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1ca90 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1caa0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1cab0 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1cac0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1cad0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1cae0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1caf0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1cb00 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1cb10 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1cb20 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1cb30 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1cb40 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1cb50 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1cb60 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1cb70 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1cb80 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1cb90 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1cba0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1cbb0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1cbc0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1cbd0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1cbe0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1cbf0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1cc00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1cc10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1cc20 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1cc30 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1cc40 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1cc50 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1cc60 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1cc70 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1cc80 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1cc90 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1cca0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1ccb0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1ccc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1ccd0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1cce0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1ccf0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1cd00 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1cd10 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1cd20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1cd30 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1cd40 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1cd50 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1cd60 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1cd70 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1cd80 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1cd90 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1cda0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1cdb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1cdc0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1cdd0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1cde0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1cdf0 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1ce00 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1ce10 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1ce20 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1ce30 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1ce40 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1ce50 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1ce60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1ce70 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1ce80 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1ce90 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1cea0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1ceb0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1cec0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1ced0 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1cee0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1cef0 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1cf00 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1cf10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1cf20 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1cf30 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1cf40 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1cf50 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1cf60 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1cf70 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1cf80 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1cf90 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1cfa0 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1cfb0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1cfc0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1cfd0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1cfe0 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1cff0 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1d000 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1d010 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1d020 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1d030 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1d040 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1d050 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1d060 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1d070 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1d080 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1d090 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1d0a0 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1d0b0 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1d0c0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1d0d0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1d0e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1d0f0 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1d100 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1d110 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1d120 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1d130 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1d140 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1d150 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1d160 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1d170 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1d180 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1d190 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1d1a0 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1d1b0 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1d1c0 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1d1d0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1d1e0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1d1f0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1d200 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1d210 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1d220 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1d230 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1d240 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1d250 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1d260 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1d270 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1d280 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1d290 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1d2a0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1d2b0 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1d2c0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1d2d0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1d2e0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1d2f0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1d300 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1d310 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1d320 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1d330 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1d340 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1d350 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1d360 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1d370 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1d380 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1d390 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1d3a0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1d3b0 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1d3c0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1d3d0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1d3e0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1d3f0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1d400 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1d410 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1d420 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1d430 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1d440 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1d450 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1d460 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1d470 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1d480 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1d490 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1d4a0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1d4b0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1d4c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1d4d0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1d4e0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1d4f0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1d500 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1d510 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1d520 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d530 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1d540 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1d550 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1d560 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1d570 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1d580 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1d590 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1d5a0 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1d5b0 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1d5c0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1d5d0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1d5e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1d5f0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1d600 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
1d610 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1d620 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
1d630 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
1d640 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
1d650 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1d660 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1d670 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1d680 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
1d690 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1d6a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1d6b0 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
1d6c0 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
1d6d0 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
1d6e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d6f0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1d700 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1d710 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1d720 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1d730 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1d740 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1d750 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1d760 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1d770 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1d780 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1d790 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1d7a0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1d7b0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1d7c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d7d0 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1d7e0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1d7f0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1d800 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1d810 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1d820 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1d830 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1d840 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1d850 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1d860 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1d870 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1d880 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1d890 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1d8a0 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1d8b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1d8c0 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1d8d0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1d8e0 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1d8f0 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1d900 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1d910 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1d920 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1d930 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1d940 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1d950 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1d960 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1d970 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1d980 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1d990 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1d9a0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1d9b0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1d9c0 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1d9d0 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1d9e0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1d9f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1da00 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1da10 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1da20 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1da30 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1da40 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1da50 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1da60 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1da70 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1da80 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1da90 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1daa0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1dab0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1dac0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1dad0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1dae0 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1daf0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1db00 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1db10 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
1db20 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1db30 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1db40 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
1db50 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1db60 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1db70 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1db80 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1db90 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1dba0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1dbb0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1dbc0 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1dbd0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1dbe0 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1dbf0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1dc00 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1dc10 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1dc20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1dc30 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1dc40 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1dc50 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1dc60 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1dc70 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1dc80 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1dc90 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1dca0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1dcb0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1dcc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1dcd0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1dce0 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1dcf0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1dd00 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1dd10 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1dd20 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1dd30 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1dd40 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1dd50 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1dd60 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
1dd70 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
1dd80 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
1dd90 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
1dda0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1ddb0 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
1ddc0 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
1ddd0 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
1dde0 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
1ddf0 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
1de00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
1de10 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
1de20 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
1de30 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1de40 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
1de50 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1de60 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
1de70 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1de80 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1de90 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1dea0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1deb0 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1dec0 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
1ded0 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
1dee0 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
1def0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1df00 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1df10 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1df20 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1df30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1df40 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1df50 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1df60 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1df70 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1df80 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1df90 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1dfa0 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1dfb0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1dfc0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1dfd0 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1dfe0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1dff0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1e000 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1e010 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1e020 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1e030 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1e040 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e050 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1e060 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1e070 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1e080 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1e090 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1e0a0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1e0b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e0c0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1e0d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1e0e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1e0f0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1e100 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1e110 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1e120 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1e130 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1e140 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1e150 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1e160 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1e170 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e180 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1e190 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1e1a0 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1e1b0 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1e1c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e1d0 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1e1e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1e1f0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1e200 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1e210 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1e220 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1e230 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1e240 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1e250 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1e260 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1e270 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1e280 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1e290 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1e2a0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1e2b0 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1e2c0 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1e2d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e2e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1e2f0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1e300 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1e310 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1e320 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1e330 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1e340 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e350 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1e360 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1e370 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1e380 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1e390 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1e3a0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1e3b0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1e3c0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1e3d0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1e3e0 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1e3f0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1e400 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1e410 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1e420 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1e430 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1e440 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1e450 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1e460 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1e470 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1e480 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1e490 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1e4a0 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1e4b0 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1e4c0 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1e4d0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1e4e0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1e4f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e500 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1e510 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1e520 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1e530 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e540 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1e550 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1e560 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1e570 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1e580 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1e590 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1e5a0 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1e5b0 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1e5c0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1e5d0 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1e5e0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1e5f0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1e600 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1e610 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1e620 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1e630 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1e640 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1e650 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1e660 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1e670 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1e680 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1e690 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1e6a0 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1e6b0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1e6c0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1e6d0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1e6e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1e6f0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1e700 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1e710 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1e720 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1e730 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1e740 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1e750 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1e760 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1e770 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1e780 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1e790 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1e7a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1e7b0 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1e7c0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1e7d0 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1e7e0 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1e7f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1e800 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1e810 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1e820 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1e830 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1e840 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1e850 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1e860 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1e870 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1e880 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1e890 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1e8a0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1e8b0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1e8c0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1e8d0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1e8e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1e8f0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1e900 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1e910 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1e920 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1e930 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1e940 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1e950 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1e960 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1e970 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1e980 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1e990 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1e9a0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1e9b0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1e9c0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1e9d0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1e9e0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1e9f0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1ea00 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1ea10 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1ea20 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1ea30 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1ea40 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1ea50 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1ea60 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1ea70 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1ea80 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1ea90 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1eaa0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1eab0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1eac0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1ead0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1eae0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1eaf0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1eb00 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1eb10 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1eb20 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1eb30 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1eb40 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1eb50 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1eb60 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1eb70 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1eb80 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1eb90 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1eba0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1ebb0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1ebc0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1ebd0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1ebe0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1ebf0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1ec00 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1ec10 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1ec20 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1ec30 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1ec40 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1ec50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1ec60 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1ec70 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1ec80 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1ec90 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1eca0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1ecb0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1ecc0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1ecd0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1ece0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1ecf0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1ed00 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1ed10 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1ed20 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1ed30 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1ed40 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1ed50 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1ed60 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ed70 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1ed80 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1ed90 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1eda0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1edb0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1edc0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1edd0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1ede0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1edf0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1ee00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1ee10 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1ee20 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1ee30 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1ee40 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1ee50 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1ee60 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1ee70 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1ee80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1ee90 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1eea0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1eeb0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1eec0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1eed0 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1eee0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1eef0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1ef00 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1ef10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1ef20 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1ef30 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1ef40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ef50 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1ef60 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1ef70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1ef80 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1ef90 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1efa0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1efb0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1efc0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1efd0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1efe0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1eff0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1f000 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1f010 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1f020 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1f030 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1f040 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1f050 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1f060 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1f070 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1f080 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1f090 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1f0a0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1f0b0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1f0c0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1f0d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
1f0e0 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
1f0f0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
1f100 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
1f110 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1f120 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1f130 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1f140 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
1f150 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
1f160 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1f170 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
1f180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1f190 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f1a0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1f1b0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1f1c0 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
1f1d0 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
1f1e0 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
1f1f0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
1f200 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
1f210 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
1f220 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1f230 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
1f240 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
1f250 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1f260 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1f270 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
1f280 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
1f290 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1f2a0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
1f2b0 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
1f2c0 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
1f2d0 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
1f2e0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
1f2f0 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
1f300 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
1f310 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
1f320 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
1f330 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f340 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1f350 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1f360 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1f370 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1f380 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1f390 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1f3a0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1f3b0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1f3c0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1f3d0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1f3e0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1f3f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1f400 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f410 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1f420 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1f430 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1f440 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1f450 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1f460 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1f470 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1f480 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1f490 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1f4a0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1f4b0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1f4c0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1f4d0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1f4e0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1f4f0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1f500 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1f510 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1f520 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f530 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1f540 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1f550 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1f560 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1f570 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1f580 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1f590 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1f5a0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1f5b0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1f5c0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1f5d0 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1f5e0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1f5f0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1f600 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1f610 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1f620 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1f630 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
1f640 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1f650 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1f660 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1f670 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1f680 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1f690 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1f6a0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1f6b0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
1f6c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1f6d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f6e0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
1f6f0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
1f700 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
1f710 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
1f720 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
1f730 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1f740 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1f750 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1f760 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1f770 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
1f780 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
1f790 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f7a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f7b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
1f7c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
1f7d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
1f7e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1f7f0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
1f800 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
1f810 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1f820 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1f830 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1f840 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
1f850 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
1f860 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1f870 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f880 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f890 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1f8a0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
1f8b0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1f8c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1f8d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f8e0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
1f8f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f900 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f910 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f920 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1f930 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
1f940 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1f950 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1f960 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f970 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1f980 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
1f990 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1f9a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f9b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f9c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
1f9d0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
1f9e0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1f9f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1fa00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fa10 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
1fa20 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
1fa30 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1fa40 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1fa50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fa60 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
1fa70 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
1fa80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1fa90 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1faa0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fab0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
1fac0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
1fad0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1fae0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1faf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fb00 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
1fb10 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
1fb20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1fb30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fb40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fb50 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
1fb60 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
1fb70 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1fb80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1fb90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fba0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
1fbb0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
1fbc0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1fbd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fbe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1fbf0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
1fc00 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
1fc10 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1fc20 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1fc30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1fc40 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
1fc50 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
1fc60 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1fc70 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fc80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1fc90 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
1fca0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
1fcb0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1fcc0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fcd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1fce0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1fcf0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
1fd00 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1fd10 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fd20 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
1fd30 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1fd40 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
1fd50 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1fd60 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1fd70 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
1fd80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1fd90 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
1fda0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
1fdb0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
1fdc0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
1fdd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
1fde0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1fdf0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1fe00 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1fe10 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
1fe20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
1fe30 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1fe40 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1fe50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fe60 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
1fe70 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
1fe80 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1fe90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1fea0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1feb0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
1fec0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
1fed0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1fee0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1fef0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ff00 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
1ff10 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
1ff20 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
1ff30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ff40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ff50 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
1ff60 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
1ff70 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1ff80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ff90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ffa0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
1ffb0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
1ffc0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1ffd0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ffe0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fff0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
20000 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
20010 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
20020 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20030 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20040 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
20050 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
20060 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20070 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20080 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20090 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
200a0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
200b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
200c0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
200d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
200e0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
200f0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
20100 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
20110 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
20120 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
20130 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
20140 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
20150 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
20160 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
20170 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
20180 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
20190 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
201a0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
201b0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
201c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
201d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
201e0 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
201f0 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
20200 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
20210 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
20220 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
20230 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
20240 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
20250 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
20260 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
20270 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
20280 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
20290 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
202a0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
202b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
202c0 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
202d0 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
202e0 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
202f0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
20300 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
20310 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
20320 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
20330 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
20340 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
20350 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
20360 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
20370 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
20380 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
20390 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
203a0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
203b0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
203c0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
203d0 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
203e0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
203f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
20400 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
20410 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
20420 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
20430 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
20440 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
20450 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
20460 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
20470 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
20480 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
20490 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
204a0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
204b0 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
204c0 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
204d0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
204e0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
204f0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
20500 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
20510 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
20520 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
20530 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
20540 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
20550 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
20560 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
20570 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
20580 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
20590 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
205a0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
205b0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
205c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
205d0 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
205e0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
205f0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
20600 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
20610 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
20620 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
20630 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
20640 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
20650 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
20660 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
20670 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
20680 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
20690 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
206a0 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
206b0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
206c0 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
206d0 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
206e0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
206f0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
20700 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
20710 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
20720 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
20730 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
20740 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
20750 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
20760 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
20770 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
20780 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
20790 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
207a0 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
207b0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
207c0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
207d0 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
207e0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
207f0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
20800 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  Lite..*/.void *s
20810 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
20820 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
20830 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
20840 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
20850 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
20860 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
20870 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
20880 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
20890 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
208a0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
208b0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
208c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
208d0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
208e0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
208f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20900 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
20910 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
20920 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
20930 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
20940 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
20950 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
20960 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
20970 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
20980 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
20990 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
209a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
209b0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
209c0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
209d0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
209e0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
209f0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
20a00 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
20a10 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
20a20 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
20a30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
20a40 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
20a50 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
20a60 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
20a70 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
20a80 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
20a90 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
20aa0 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
20ab0 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
20ac0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
20ad0 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
20ae0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
20af0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
20b00 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
20b10 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
20b20 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
20b30 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
20b40 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
20b50 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
20b60 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
20b70 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
20b80 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20b90 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
20ba0 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
20bb0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
20bc0 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
20bd0 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
20be0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
20bf0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
20c00 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
20c10 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
20c20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
20c30 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
20c40 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
20c50 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
20c60 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
20c70 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
20c80 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
20c90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
20ca0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
20cb0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
20cc0 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
20cd0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
20ce0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
20cf0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
20d00 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
20d10 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
20d20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
20d30 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
20d40 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
20d50 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
20d60 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
20d70 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
20d80 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
20d90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20da0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
20db0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
20dc0 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
20dd0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
20de0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
20df0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
20e00 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
20e10 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
20e20 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
20e30 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
20e40 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
20e50 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
20e60 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
20e70 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
20e80 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
20e90 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
20ea0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20eb0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
20ec0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
20ed0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
20ee0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
20ef0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
20f00 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
20f10 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
20f20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
20f30 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
20f40 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
20f50 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
20f60 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
20f70 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
20f80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
20f90 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
20fa0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
20fb0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
20fc0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
20fd0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
20fe0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
20ff0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
21000 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
21010 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
21020 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
21030 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
21040 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
21050 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
21060 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
21070 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
21080 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
21090 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
210a0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
210b0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
210c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
210d0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
210e0 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
210f0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
21100 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
21110 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
21120 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
21130 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
21140 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
21150 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
21160 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
21170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
21180 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
21190 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
211a0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
211b0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
211c0 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
211d0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
211e0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
211f0 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
21200 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
21210 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
21220 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
21230 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
21240 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
21250 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
21260 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
21270 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
21280 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
21290 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
212a0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
212b0 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
212c0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
212d0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
212e0 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
212f0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
21300 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
21310 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
21320 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
21330 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
21340 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
21350 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
21360 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
21370 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
21380 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
21390 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
213a0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
213b0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
213c0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
213d0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
213e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
213f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
21400 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
21410 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
21420 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
21430 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
21440 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
21450 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
21460 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
21470 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
21480 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
21490 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
214a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
214b0 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
214c0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
214d0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
214e0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
214f0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
21500 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
21510 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
21520 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
21530 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
21540 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
21550 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
21560 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
21570 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
21580 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
21590 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
215a0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
215b0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
215c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
215d0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
215e0 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
215f0 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
21600 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
21610 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
21620 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
21630 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
21640 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
21650 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
21660 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21670 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21680 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
21690 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
216a0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
216b0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
216c0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
216d0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
216e0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
216f0 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
21700 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
21710 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
21720 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
21730 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
21740 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
21750 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
21760 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
21770 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
21780 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
21790 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
217a0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
217b0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
217c0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
217d0 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
217e0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
217f0 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
21800 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
21810 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
21820 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
21830 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
21840 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
21850 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
21860 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
21870 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
21880 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
21890 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
218a0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
218b0 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
218c0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
218d0 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
218e0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
218f0 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
21900 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
21910 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
21920 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
21930 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
21940 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
21950 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
21960 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21970 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
21980 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
21990 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
219a0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
219b0 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
219c0 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
219d0 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
219e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
219f0 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
21a00 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
21a10 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
21a20 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
21a30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21a40 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
21a50 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
21a60 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
21a70 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
21a80 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
21a90 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
21aa0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
21ab0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
21ac0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
21ad0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
21ae0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
21af0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21b00 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
21b10 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
21b20 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
21b30 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
21b40 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
21b50 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
21b60 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
21b70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
21b80 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
21b90 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
21ba0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
21bb0 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
21bc0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
21bd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
21be0 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
21bf0 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
21c00 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
21c10 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
21c20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
21c30 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21c40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21c50 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
21c60 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
21c70 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
21c80 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
21c90 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
21ca0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
21cb0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
21cc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
21cd0 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
21ce0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
21cf0 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
21d00 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
21d10 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
21d20 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
21d30 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
21d40 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
21d50 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
21d60 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
21d70 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
21d80 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
21d90 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
21da0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
21db0 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
21dc0 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
21dd0 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
21de0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21df0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
21e00 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
21e10 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
21e20 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
21e30 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
21e40 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
21e50 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
21e60 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
21e70 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
21e80 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
21e90 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
21ea0 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
21eb0 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
21ec0 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
21ed0 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
21ee0 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
21ef0 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
21f00 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
21f10 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
21f20 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
21f30 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
21f40 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
21f50 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
21f60 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
21f70 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
21f80 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
21f90 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
21fa0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
21fb0 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
21fc0 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
21fd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21fe0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
21ff0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
22000 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
22010 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
22020 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
22030 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
22040 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
22050 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
22060 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
22070 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
22080 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
22090 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
220a0 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
220b0 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
220c0 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
220d0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
220e0 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
220f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
22100 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
22110 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
22120 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
22130 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22140 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
22150 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
22160 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
22170 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
22180 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
22190 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
221a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
221b0 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
221c0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
221d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
221e0 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
221f0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
22200 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
22210 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
22220 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
22230 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
22240 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
22250 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
22260 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
22270 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
22280 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
22290 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
222a0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
222b0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
222c0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
222d0 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
222e0 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
222f0 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
22300 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
22310 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
22320 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
22330 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
22340 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
22350 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
22360 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
22370 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
22380 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
22390 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
223a0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
223b0 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
223c0 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
223d0 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
223e0 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
223f0 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
22400 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
22410 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
22420 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
22430 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
22440 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
22450 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
22460 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
22470 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
22480 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
22490 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
224a0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
224b0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
224c0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
224d0 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
224e0 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
224f0 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
22500 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
22510 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
22520 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
22530 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
22540 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
22550 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
22560 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
22570 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68  ^(On windows, th
22580 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
22590 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
225a0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
225b0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
225c0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29  on (e.g. "C:").)
225d0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ^.**.** [[core U
225e0 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
225f0 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
22600 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
22610 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
22620 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
22630 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
22640 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
22650 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
22660 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
22670 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
22680 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
22690 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74  te and its built
226a0 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65  -in [VFSes] inte
226b0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c  rpret the.** fol
226c0 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72  lowing query par
226d0 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
226e0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
226f0 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
22700 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
22710 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
22720 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
22730 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
22740 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
22750 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
22760 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
22770 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
22780 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
22790 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
227a0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
227b0 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
227c0 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
227d0 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
227e0 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
227f0 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
22800 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
22810 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
22820 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
22830 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
22840 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
22850 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
22860 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
22870 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
22880 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
22890 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
228a0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
228b0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
228c0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
228d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
228e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
228f0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
22900 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
22910 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
22920 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
22930 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
22940 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
22950 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
22960 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
22970 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
22980 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
22990 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
229a0 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
229b0 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
229c0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
229d0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
229e0 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
229f0 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
22a00 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
22a10 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
22a20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
22a30 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
22a40 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
22a50 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
22a60 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
22a70 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
22a80 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
22a90 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
22aa0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
22ab0 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
22ac0 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
22ad0 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
22ae0 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
22af0 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
22b00 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
22b10 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
22b20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
22b30 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
22b40 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
22b50 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
22b60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
22b70 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
22b80 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
22b90 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
22ba0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
22bb0 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
22bc0 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
22bd0 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
22be0 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
22bf0 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
22c00 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
22c10 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
22c20 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
22c30 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
22c40 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
22c50 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
22c60 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
22c70 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
22c80 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
22c90 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
22ca0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
22cb0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
22cc0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
22cd0 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
22ce0 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
22cf0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
22d00 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
22d10 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
22d20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
22d30 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
22d40 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
22d50 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
22d60 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
22d70 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
22d80 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
22d90 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
22da0 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
22db0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
22dc0 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
22dd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
22de0 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
22df0 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
22e00 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
22e10 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
22e20 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
22e30 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
22e40 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
22e50 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
22e60 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
22e70 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
22e80 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
22e90 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
22ea0 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
22eb0 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
22ec0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
22ed0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
22ee0 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
22ef0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
22f00 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  flag..**.**  <li
22f10 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e  > <b>psow</b>: ^
22f20 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74  The psow paramet
22f30 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65  er indicates whe
22f40 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a  ther or not the.
22f50 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66  **     [powersaf
22f60 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f  e overwrite] pro
22f70 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f  perty does or do
22f80 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20  es not apply to 
22f90 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61  the.**     stora
22fa0 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63  ge media on whic
22fb0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  h the database f
22fc0 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a  ile resides..**.
22fd0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
22fe0 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
22ff0 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
23000 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
23010 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
23020 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
23030 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
23040 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
23050 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
23060 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
23070 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
23080 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
23090 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
230a0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
230b0 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
230c0 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
230d0 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
230e0 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
230f0 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
23100 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
23110 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
23120 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
23130 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
23140 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
23150 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
23160 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
23170 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
23180 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
23190 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
231a0 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
231b0 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
231c0 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
231d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
231e0 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
231f0 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
23200 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
23210 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
23220 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
23230 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
23240 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
23250 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
23260 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
23270 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
23280 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
23290 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
232a0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
232b0 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
232c0 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
232d0 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
232e0 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
232f0 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
23300 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
23310 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
23320 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
23330 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
23340 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
23350 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
23360 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
23370 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
23380 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
23390 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
233a0 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
233b0 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
233c0 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
233d0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
233e0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
233f0 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
23400 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
23410 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
23420 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
23430 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
23440 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
23450 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
23460 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
23470 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
23480 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
23490 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
234a0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
234b0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
234c0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
234d0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
234e0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
234f0 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
23500 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
23510 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
23520 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
23530 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
23540 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
23550 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
23560 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
23570 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
23580 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
23590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
235a0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
235b0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
235c0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
235d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
235e0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
235f0 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
23600 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
23610 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
23620 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
23630 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
23640 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
23650 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
23660 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
23670 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
23680 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
23690 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
236a0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
236b0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
236c0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
236d0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
236e0 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
236f0 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
23700 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
23710 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
23720 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
23730 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
23740 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
23750 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
23760 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
23770 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
23780 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
23790 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
237a0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
237b0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
237c0 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
237d0 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
237e0 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
237f0 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
23800 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
23810 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
23820 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
23830 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
23840 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
23850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
23860 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
23870 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23880 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
23890 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
238a0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
238b0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
238c0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
238d0 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
238e0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
238f0 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
23900 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
23910 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
23920 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
23930 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
23940 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
23950 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
23960 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
23970 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
23980 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
23990 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
239a0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
239b0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
239c0 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
239d0 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
239e0 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
239f0 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
23a00 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
23a10 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
23a20 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
23a30 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
23a40 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
23a50 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
23a60 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
23a70 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
23a80 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
23a90 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
23aa0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
23ab0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
23ac0 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
23ad0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
23ae0 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
23af0 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
23b00 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
23b10 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
23b20 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
23b30 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23b40 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
23b50 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
23b60 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
23b70 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
23b80 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
23b90 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
23ba0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
23bb0 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
23bc0 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
23bd0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
23be0 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
23bf0 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
23c00 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
23c10 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
23c20 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
23c30 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23c40 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
23c50 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
23c60 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
23c70 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
23c80 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
23c90 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
23ca0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
23cb0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
23cc0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
23cd0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
23ce0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
23cf0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
23d00 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
23d10 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
23d20 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
23d30 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
23d40 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
23d50 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
23d60 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
23d70 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
23d80 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
23d90 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
23da0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
23db0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
23dc0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
23dd0 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
23de0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
23df0 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
23e00 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
23e10 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
23e20 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
23e30 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
23e40 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
23e50 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
23e60 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
23e70 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
23e80 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
23e90 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
23ea0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23eb0 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
23ec0 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
23ed0 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
23ee0 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
23ef0 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
23f00 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
23f10 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
23f20 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
23f30 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
23f40 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
23f50 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
23f60 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
23f70 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
23f80 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
23f90 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
23fa0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
23fb0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
23fc0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
23fd0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
23fe0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
23ff0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
24000 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
24010 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
24020 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
24030 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
24040 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24050 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
24060 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
24070 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
24080 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
24090 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
240a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
240b0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
240c0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
240d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
240e0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
240f0 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
24100 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
24110 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
24120 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
24130 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
24140 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
24150 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
24160 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
24170 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
24180 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
24190 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
241a0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
241b0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
241c0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
241d0 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
241e0 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
241f0 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
24200 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
24210 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
24220 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
24230 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
24240 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
24250 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
24260 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
24270 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
24280 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
24290 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
242a0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
242b0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
242c0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
242d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
242e0 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
242f0 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
24300 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
24310 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
24320 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
24330 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
24340 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
24350 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
24360 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
24370 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
24380 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
24390 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
243a0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
243b0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
243c0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
243d0 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
243e0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
243f0 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
24400 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
24410 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
24420 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
24430 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
24440 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
24450 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
24460 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24470 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
24480 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
24490 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
244a0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
244b0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
244c0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
244d0 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
244e0 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
244f0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
24500 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
24510 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
24520 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
24530 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
24540 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
24550 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
24560 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
24570 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
24580 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
24590 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
245a0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
245b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
245c0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
245d0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
245e0 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
245f0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
24600 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
24610 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
24620 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
24630 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
24640 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
24650 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
24660 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
24670 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
24680 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
24690 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
246a0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
246b0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
246c0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
246d0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
246e0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
246f0 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
24700 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24710 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
24720 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
24730 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
24740 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
24750 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
24760 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
24770 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
24780 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
24790 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
247a0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
247b0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
247c0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
247d0 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
247e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
247f0 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
24800 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
24810 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
24820 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
24830 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
24840 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
24850 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
24860 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
24870 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
24880 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
24890 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
248a0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
248b0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
248c0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
248d0 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
248e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
248f0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
24900 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
24910 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
24920 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
24930 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
24940 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
24950 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
24960 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
24970 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
24980 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24990 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
249a0 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
249b0 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
249c0 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
249d0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
249e0 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
249f0 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
24a00 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
24a10 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
24a20 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
24a30 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
24a40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
24a50 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
24a60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
24a70 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
24a80 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
24a90 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24aa0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
24ab0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
24ac0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
24ad0 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
24ae0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
24af0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
24b00 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
24b10 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
24b20 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
24b30 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
24b40 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
24b50 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
24b60 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
24b70 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
24b80 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
24b90 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
24ba0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
24bb0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
24bc0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
24bd0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
24be0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24bf0 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
24c00 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24c10 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
24c20 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
24c30 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
24c40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
24c50 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
24c60 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
24c70 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
24c80 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
24c90 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
24ca0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
24cb0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
24cc0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
24cd0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
24ce0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
24cf0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
24d00 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
24d10 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
24d20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
24d30 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
24d40 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
24d50 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
24d60 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
24d70 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
24d80 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
24d90 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
24da0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
24db0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
24dc0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
24dd0 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
24de0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24df0 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
24e00 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
24e10 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
24e20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
24e30 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
24e40 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
24e50 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
24e60 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
24e70 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
24e80 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
24e90 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
24ea0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
24eb0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
24ec0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
24ed0 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
24ee0 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
24ef0 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
24f00 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
24f10 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
24f20 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
24f30 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
24f40 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
24f50 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
24f60 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
24f70 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
24f80 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
24f90 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
24fa0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
24fb0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
24fc0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
24fd0 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
24fe0 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
24ff0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
25000 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
25010 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
25020 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
25030 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25040 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
25050 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
25060 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
25070 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
25080 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
25090 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
250a0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
250b0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
250c0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
250d0 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
250e0 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
250f0 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
25100 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
25110 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
25120 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
25130 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
25140 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
25150 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
25160 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
25170 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
25180 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
25190 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
251a0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
251b0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
251c0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
251d0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
251e0 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
251f0 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
25200 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
25210 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
25220 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
25230 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
25240 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
25250 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
25260 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
25270 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
25280 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
25290 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
252a0 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
252b0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
252c0 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
252d0 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
252e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
252f0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
25300 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
25310 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
25320 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
25330 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
25340 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
25350 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
25360 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
25370 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
25380 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
25390 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
253a0 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
253b0 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
253c0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
253d0 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
253e0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
253f0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
25400 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
25410 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25420 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
25430 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
25440 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
25450 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
25460 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
25470 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
25480 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
25490 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
254a0 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
254b0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
254c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
254d0 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
254e0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
254f0 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
25500 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
25510 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
25520 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
25530 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
25540 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
25550 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
25560 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
25570 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
25580 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
25590 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
255a0 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
255b0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
255c0 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
255d0 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
255e0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
255f0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
25600 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
25610 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
25620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
25630 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
25640 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
25650 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
25660 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
25670 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
25680 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
25690 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
256a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
256b0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
256c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
256d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
256e0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
256f0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
25700 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
25710 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
25720 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
25730 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
25740 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
25750 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
25760 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
25770 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
25780 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
25790 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
257a0 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
257b0 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
257c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
257d0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
257e0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
257f0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
25800 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
25810 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
25820 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
25830 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
25840 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
25850 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
25860 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
25870 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
25880 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
25890 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
258a0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
258b0 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
258c0 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
258d0 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
258e0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
258f0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
25900 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
25910 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
25920 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
25930 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
25940 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
25950 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
25960 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
25970 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
25980 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
25990 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
259a0 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
259b0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
259c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
259d0 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
259e0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
259f0 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
25a00 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
25a10 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
25a20 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
25a30 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
25a40 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
25a50 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
25a60 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
25a70 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
25a80 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
25a90 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
25aa0 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
25ab0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
25ac0 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
25ad0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
25ae0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
25af0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
25b00 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
25b10 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
25b20 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
25b30 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
25b40 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
25b50 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
25b60 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
25b70 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
25b80 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
25b90 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
25ba0 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
25bb0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
25bc0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
25bd0 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
25be0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
25bf0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
25c00 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
25c10 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
25c20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
25c30 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
25c40 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
25c50 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
25c60 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
25c70 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
25c80 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
25c90 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
25ca0 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
25cb0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
25cc0 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
25cd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
25ce0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
25cf0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
25d00 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
25d10 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
25d20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
25d30 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
25d40 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
25d50 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
25d60 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
25d70 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
25d80 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
25d90 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
25da0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
25db0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
25dc0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
25dd0 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
25de0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
25df0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
25e00 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
25e10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
25e20 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
25e30 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
25e40 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
25e50 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
25e60 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
25e70 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
25e80 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
25e90 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
25ea0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
25eb0 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
25ec0 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
25ed0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
25ee0 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
25ef0 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
25f00 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
25f10 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
25f20 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
25f30 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
25f40 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
25f50 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
25f60 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
25f70 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
25f80 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
25f90 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25fa0 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
25fb0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25fc0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
25fd0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
25fe0 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
25ff0 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
26000 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26010 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
26020 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26030 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
26040 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26050 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
26060 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
26070 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
26080 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26090 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
260a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
260b0 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
260c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
260d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
260e0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
260f0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
26100 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
26110 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
26120 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
26130 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
26140 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
26150 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
26160 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
26170 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
26180 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26190 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
261a0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
261b0 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
261c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
261d0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
261e0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
261f0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
26200 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26210 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
26220 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
26230 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26240 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
26250 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26260 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
26270 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
26280 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
26290 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
262a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
262b0 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
262c0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
262d0 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
262e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
262f0 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
26300 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
26310 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
26320 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
26330 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
26340 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
26350 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
26360 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
26370 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
26380 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
26390 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
263a0 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
263b0 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
263c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
263d0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
263e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
263f0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
26400 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26410 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
26420 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
26430 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
26440 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
26450 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
26460 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
26470 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
26480 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26490 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
264a0 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
264b0 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
264c0 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
264d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
264e0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
264f0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
26500 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
26510 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
26520 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26530 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
26540 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
26550 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
26560 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
26570 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
26580 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26590 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
265a0 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
265b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
265c0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
265d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
265e0 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
265f0 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
26600 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
26610 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
26620 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26630 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
26640 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26650 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
26660 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
26670 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
26680 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
26690 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
266a0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
266b0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
266c0 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
266d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
266e0 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
266f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26700 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
26710 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
26720 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
26730 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
26740 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
26750 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
26760 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
26770 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
26780 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
26790 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
267a0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
267b0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
267c0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
267d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
267e0 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
267f0 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
26800 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26810 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
26820 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
26830 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26840 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
26850 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
26860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26870 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
26880 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
26890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
268a0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
268b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
268c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
268d0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
268e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
268f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26900 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
26910 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
26920 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
26930 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
26940 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
26950 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
26960 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
26970 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
26980 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
26990 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
269a0 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
269b0 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
269c0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
269d0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
269e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
269f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
26a00 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
26a10 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
26a20 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
26a30 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
26a40 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
26a50 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
26a60 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
26a70 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
26a80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
26a90 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
26aa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26ab0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
26ac0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
26ad0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
26ae0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
26af0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
26b00 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
26b10 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
26b20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
26b30 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
26b40 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
26b50 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
26b60 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
26b70 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
26b80 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
26b90 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
26ba0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
26bb0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
26bc0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
26bd0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
26be0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
26bf0 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
26c00 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
26c10 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
26c20 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26c30 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
26c40 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
26c50 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
26c60 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
26c70 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
26c80 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
26c90 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
26ca0 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
26cb0 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
26cc0 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
26cd0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
26ce0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
26cf0 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
26d00 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
26d10 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
26d20 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
26d30 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
26d40 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
26d50 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
26d60 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
26d70 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
26d80 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
26d90 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
26da0 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
26db0 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
26dc0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
26dd0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
26de0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
26df0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
26e00 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
26e10 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
26e20 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
26e30 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
26e40 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
26e50 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
26e60 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
26e70 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
26e80 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
26e90 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
26ea0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
26eb0 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
26ec0 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
26ed0 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
26ee0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
26ef0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
26f00 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
26f10 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
26f20 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
26f30 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
26f40 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
26f50 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
26f60 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
26f70 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
26f80 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
26f90 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
26fa0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
26fb0 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
26fc0 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
26fd0 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
26fe0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
26ff0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
27000 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
27010 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
27020 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
27030 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
27040 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
27050 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
27060 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
27070 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
27080 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
27090 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
270a0 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
270b0 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
270c0 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
270d0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
270e0 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
270f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
27100 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
27110 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
27120 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
27130 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
27140 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
27150 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27160 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
27170 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
27180 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
27190 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
271a0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
271b0 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
271c0 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
271d0 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
271e0 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
271f0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
27200 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
27210 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
27220 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
27230 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
27240 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
27250 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
27260 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
27270 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
27280 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
27290 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
272a0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
272b0 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
272c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
272d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
272e0 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
272f0 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
27300 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
27310 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
27320 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
27330 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
27340 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
27350 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
27360 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
27370 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
27380 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
27390 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
273a0 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
273b0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
273c0 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
273d0 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
273e0 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
273f0 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
27400 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
27410 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
27420 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
27430 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
27440 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
27450 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
27460 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
27470 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
27480 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
27490 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
274a0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
274b0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
274c0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
274d0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
274e0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
274f0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
27500 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
27510 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
27520 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
27530 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
27540 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
27550 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
27560 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
27570 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
27580 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
27590 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
275a0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
275b0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
275c0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
275d0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
275e0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
275f0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
27600 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
27610 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
27620 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
27630 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
27640 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
27650 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
27660 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
27670 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
27680 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
27690 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
276a0 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
276b0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
276c0 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
276d0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
276e0 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
276f0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
27700 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
27710 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
27720 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
27730 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
27740 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
27750 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
27760 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
27770 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
27780 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
27790 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
277a0 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
277b0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
277c0 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
277d0 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
277e0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
277f0 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
27800 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
27810 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
27820 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
27830 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
27840 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
27850 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
27860 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
27870 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
27880 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
27890 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
278a0 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
278b0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
278c0 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
278d0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
278e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
278f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
27900 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
27910 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
27920 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
27930 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
27940 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
27950 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
27960 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
27970 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
27980 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
27990 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
279a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
279b0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
279c0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
279d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
279e0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
279f0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
27a00 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
27a10 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
27a20 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
27a30 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
27a40 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
27a50 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
27a60 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
27a70 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
27a80 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
27a90 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
27aa0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
27ab0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
27ac0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
27ad0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
27ae0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
27af0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
27b00 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
27b10 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27b20 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
27b30 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
27b40 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
27b50 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
27b60 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
27b70 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
27b80 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
27b90 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
27ba0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27bb0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
27bc0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
27bd0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
27be0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
27bf0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
27c00 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
27c10 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
27c20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
27c30 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
27c40 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
27c50 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
27c60 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
27c70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
27c80 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
27c90 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
27ca0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
27cb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27cc0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
27cd0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
27ce0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
27cf0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
27d00 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
27d10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
27d20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
27d30 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
27d40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
27d50 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27d60 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
27d70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
27d80 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
27d90 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
27da0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27db0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
27dc0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
27dd0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
27de0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
27df0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27e00 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
27e10 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a  tatement SQL.**.
27e20 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
27e30 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
27e40 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
27e50 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
27e60 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
27e70 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
27e80 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
27e90 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
27ea0 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
27eb0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
27ec0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
27ed0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
27ee0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
27ef0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
27f00 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
27f10 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
27f20 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
27f30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
27f40 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
27f50 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
27f60 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
27f70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27f80 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
27f90 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
27fa0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
27fb0 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
27fc0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
27fd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27fe0 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
27ff0 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
28000 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
28010 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
28020 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
28030 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
28040 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
28050 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
28060 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
28070 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
28080 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
28090 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
280a0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
280b0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
280c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
280d0 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
280e0 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
280f0 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
28100 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
28110 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
28120 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
28130 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
28140 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
28150 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
28160 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
28170 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
28180 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
28190 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
281a0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
281b0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
281c0 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
281d0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
281e0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
281f0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
28200 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
28210 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
28220 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
28230 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
28240 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
28250 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
28260 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
28270 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
28280 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
28290 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
282a0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
282b0 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
282c0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
282d0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
282e0 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
282f0 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
28300 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
28310 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
28320 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
28330 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
28340 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
28350 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
28360 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
28370 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
28380 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
28390 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
283a0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
283b0 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
283c0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
283d0 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
283e0 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
283f0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
28400 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
28410 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
28420 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
28430 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
28440 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
28450 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
28460 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
28470 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69  es on disk..*/.i
28480 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
28490 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
284a0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
284b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
284c0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
284d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
284e0 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
284f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28500 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
28510 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28520 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
28530 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
28540 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28550 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
28560 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
28570 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
28580 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
28590 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
285a0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
285b0 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
285c0 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
285d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
285e0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
285f0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
28600 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
28610 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
28620 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
28630 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
28640 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
28650 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
28660 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
28670 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
28680 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
28690 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
286a0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
286b0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
286c0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
286d0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
286e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
286f0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
28700 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
28710 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
28720 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
28730 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
28740 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
28750 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
28760 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
28770 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
28780 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
28790 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
287a0 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
287b0 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
287c0 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
287d0 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
287e0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
287f0 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
28800 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
28810 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
28820 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
28830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28840 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
28850 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
28860 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
28870 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28880 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
28890 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
288a0 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
288b0 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
288c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
288d0 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
288e0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
288f0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
28900 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
28910 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
28920 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
28930 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
28940 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
28950 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
28960 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28970 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
28980 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
28990 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
289a0 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
289b0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
289c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
289d0 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
289e0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
289f0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
28a00 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
28a10 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
28a20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28a30 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
28a40 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
28a50 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
28a60 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
28a70 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
28a80 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
28a90 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
28aa0 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
28ab0 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
28ac0 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
28ad0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
28ae0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
28af0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28b00 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
28b10 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
28b20 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
28b30 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
28b40 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
28b50 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
28b60 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
28b70 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
28b80 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
28b90 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28ba0 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
28bb0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
28bc0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
28bd0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28be0 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
28bf0 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
28c00 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
28c10 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
28c20 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
28c30 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
28c40 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
28c50 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
28c60 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
28c70 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
28c80 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
28c90 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
28ca0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
28cb0 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
28cc0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
28cd0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
28ce0 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
28cf0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
28d00 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
28d10 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
28d20 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
28d30 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
28d40 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
28d50 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
28d60 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
28d70 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
28d80 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
28d90 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
28da0 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
28db0 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
28dc0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
28dd0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
28de0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
28df0 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
28e00 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
28e10 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
28e20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
28e30 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
28e40 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
28e50 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
28e60 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
28e70 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
28e80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
28e90 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
28ea0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
28eb0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
28ec0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
28ed0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
28ee0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
28ef0 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
28f00 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
28f10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28f20 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
28f30 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
28f40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
28f50 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
28f60 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
28f70 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
28f80 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
28f90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
28fa0 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
28fb0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
28fc0 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
28fd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28fe0 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
28ff0 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
29000 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
29010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
29020 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
29030 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
29040 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
29050 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
29060 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
29070 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
29080 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
29090 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
290a0 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
290b0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
290c0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
290d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
290e0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
290f0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
29100 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
29110 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29120 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
29130 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
29140 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
29150 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
29160 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
29170 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
29180 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
29190 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
291a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
291b0 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
291c0 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
291d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
291e0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
291f0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
29200 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
29210 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
29220 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
29230 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
29240 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
29250 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
29260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29270 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
29280 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
29290 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
292a0 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
292b0 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
292c0 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
292d0 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
292e0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
292f0 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
29300 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
29310 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
29320 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
29330 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
29340 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
29350 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29360 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
29370 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
29380 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
29390 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
293a0 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
293b0 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
293c0 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
293d0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
293e0 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
293f0 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
29400 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
29410 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
29420 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
29430 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
29440 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
29450 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
29460 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
29470 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
29480 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
29490 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
294a0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
294b0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
294c0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
294d0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
294e0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
294f0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
29500 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
29510 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
29520 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
29530 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
29540 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
29550 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
29560 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
29570 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
29580 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
29590 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
295a0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
295b0 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
295c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
295d0 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
295e0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
295f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
29600 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
29610 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
29620 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
29630 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
29640 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
29650 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
29660 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
29670 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
29680 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
29690 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
296a0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
296b0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
296c0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
296d0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
296e0 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
296f0 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
29700 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
29710 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
29720 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
29730 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29740 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
29750 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
29760 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
29770 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
29780 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
29790 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
297a0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
297b0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
297c0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
297d0 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
297e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
297f0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
29800 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
29810 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
29820 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
29830 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
29840 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
29850 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
29860 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
29870 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
29880 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
29890 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
298a0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
298b0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
298c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
298d0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
298e0 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
298f0 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
29900 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
29910 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
29920 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
29930 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
29940 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
29950 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
29960 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
29970 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
29980 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
29990 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
299a0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
299b0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
299c0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
299d0 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
299e0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
299f0 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
29a00 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
29a10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29a20 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
29a30 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
29a40 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
29a50 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
29a60 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
29a70 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
29a80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
29a90 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
29aa0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
29ab0 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
29ac0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
29ad0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
29ae0 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
29af0 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
29b00 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
29b10 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
29b20 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
29b30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
29b40 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
29b50 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
29b60 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
29b70 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
29b80 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
29b90 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
29ba0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
29bb0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
29bc0 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
29bd0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
29be0 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
29bf0 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
29c00 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
29c10 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
29c20 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
29c30 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
29c40 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
29c50 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
29c60 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29c70 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
29c80 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
29c90 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
29ca0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
29cb0 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
29cc0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
29cd0 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
29ce0 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
29cf0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
29d00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
29d10 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
29d20 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
29d30 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
29d40 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
29d50 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
29d60 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
29d70 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
29d80 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
29d90 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
29da0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
29db0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
29dc0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
29dd0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
29de0 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
29df0 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
29e00 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
29e10 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
29e20 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
29e30 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
29e40 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
29e50 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
29e60 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
29e70 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
29e80 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
29e90 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
29ea0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
29eb0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
29ec0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
29ed0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
29ee0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
29ef0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
29f00 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
29f10 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
29f20 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
29f30 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
29f40 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29f50 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
29f60 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
29f70 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
29f80 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
29f90 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
29fa0 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
29fb0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
29fc0 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
29fd0 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
29fe0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
29ff0 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
2a000 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2a010 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
2a020 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
2a030 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
2a040 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2a050 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2a060 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
2a070 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
2a080 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
2a090 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
2a0a0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2a0b0 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
2a0c0 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2a0d0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
2a0e0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
2a0f0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
2a100 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2a110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a120 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2a130 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2a140 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2a150 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2a160 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2a170 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2a180 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2a190 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2a1a0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2a1b0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2a1c0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2a1d0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2a1e0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2a1f0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2a200 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2a210 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2a220 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2a230 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2a240 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2a250 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2a260 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2a270 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2a280 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2a290 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2a2a0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2a2b0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2a2c0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
2a2d0 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
2a2e0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2a2f0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
2a300 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
2a310 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
2a320 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a330 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
2a340 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
2a350 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
2a360 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2a370 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
2a380 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
2a390 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a3a0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
2a3b0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
2a3c0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2a3d0 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
2a3e0 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
2a3f0 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
2a400 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a410 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
2a420 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
2a430 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
2a440 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2a450 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
2a460 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
2a470 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
2a480 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
2a490 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
2a4a0 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
2a4b0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
2a4c0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
2a4d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a4e0 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
2a4f0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2a500 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2a510 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
2a520 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
2a530 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2a540 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
2a550 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
2a560 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
2a570 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
2a580 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
2a590 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
2a5a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2a5b0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2a5c0 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
2a5d0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
2a5e0 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
2a5f0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
2a600 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
2a610 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
2a620 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
2a630 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
2a640 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
2a650 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
2a660 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a670 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a680 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2a690 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a6a0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2a6b0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2a6c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a6d0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2a6e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2a6f0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2a700 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2a710 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
2a720 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2a730 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2a740 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2a750 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2a760 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
2a770 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2a780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2a790 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2a7a0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2a7b0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2a7c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
2a7d0 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
2a7e0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
2a7f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2a800 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2a810 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
2a820 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2a830 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
2a840 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
2a850 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
2a860 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
2a870 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
2a880 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2a890 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
2a8a0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2a8b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2a8c0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2a8d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2a8e0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2a8f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2a900 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2a910 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
2a920 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2a930 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2a940 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2a950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a960 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2a970 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
2a980 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20   encoding);.int 
2a990 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2a9a0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2a9b0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
2a9c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2a9d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2a9e0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2a9f0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2aa00 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
2aa10 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
2aa20 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
2aa30 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2aa40 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2aa50 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
2aa60 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
2aa70 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
2aa80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2aa90 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
2aaa0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
2aab0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
2aac0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
2aad0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
2aae0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
2aaf0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
2ab00 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
2ab10 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
2ab20 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
2ab30 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
2ab40 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
2ab50 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
2ab60 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
2ab70 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
2ab80 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
2ab90 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
2aba0 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
2abb0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
2abc0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
2abd0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
2abe0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
2abf0 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
2ac00 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
2ac10 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
2ac20 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
2ac30 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
2ac40 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
2ac50 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
2ac60 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2ac70 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2ac80 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2ac90 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2aca0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2acb0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2acc0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2acd0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2ace0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2acf0 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
2ad00 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2ad10 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2ad20 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
2ad30 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eter.**.** ^The 
2ad40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2ad50 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
2ad60 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ad70 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
2ad80 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
2ad90 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2ada0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2adb0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
2adc0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
2add0 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
2ade0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2adf0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2ae00 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
2ae10 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
2ae20 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
2ae30 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2ae40 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
2ae50 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
2ae60 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
2ae70 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
2ae80 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
2ae90 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
2aea0 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
2aeb0 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
2aec0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2aed0 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
2aee0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
2aef0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
2af00 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
2af10 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
2af20 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
2af30 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
2af40 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
2af50 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
2af60 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
2af70 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
2af80 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
2af90 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
2afa0 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
2afb0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
2afc0 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
2afd0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
2afe0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2aff0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
2b000 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
2b010 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
2b020 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
2b030 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
2b040 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
2b050 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
2b060 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
2b070 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2b080 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2b090 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b0a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b0b0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2b0c0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2b0d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2b0e0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2b0f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b100 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2b110 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2b120 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b130 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
2b140 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2b150 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b160 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
2b170 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
2b180 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52  en Name.**.** ^R
2b190 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
2b1a0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
2b1b0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
2b1c0 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
2b1d0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
2b1e0 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
2b1f0 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
2b200 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
2b210 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
2b220 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2b230 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
2b240 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2b250 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
2b260 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
2b270 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
2b280 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
2b290 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
2b2a0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
2b2b0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
2b2c0 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
2b2d0 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
2b2e0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2b2f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2b300 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2b310 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2b320 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2b330 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2b340 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2b350 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2b360 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b370 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2b380 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2b390 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b3a0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2b3b0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2b3c0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2b3d0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2b3e0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2b3f0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2b400 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  tement.**.** ^Co
2b410 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
2b420 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
2b430 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b440 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
2b450 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
2b460 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
2b470 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
2b480 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b490 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
2b4a0 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
2b4b0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
2b4c0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
2b4d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
2b4e0 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2b4f0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2b500 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2b510 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2b520 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2b530 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2b540 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2b550 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2b560 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
2b570 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2b580 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
2b590 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2b5a0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
2b5b0 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
2b5c0 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
2b5d0 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
2b5e0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
2b5f0 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
2b600 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b610 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
2b620 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2b630 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
2b640 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b650 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b660 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
2b670 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2b680 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2b690 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2b6a0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
2b6b0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
2b6c0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
2b6d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2b6e0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2b6f0 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
2b700 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2b710 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2b720 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2b730 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2b740 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
2b750 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
2b760 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2b770 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
2b780 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2b790 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
2b7a0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2b7b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2b7c0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
2b7d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2b7e0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2b7f0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2b800 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
2b810 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2b820 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
2b830 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
2b840 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
2b850 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
2b860 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2b870 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
2b880 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
2b890 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
2b8a0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
2b8b0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
2b8c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2b8d0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2b8e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2b8f0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2b900 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2b910 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2b920 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2b930 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2b940 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2b950 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2b960 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2b970 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
2b980 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2b990 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
2b9a0 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
2b9b0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
2b9c0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
2b9d0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
2b9e0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
2b9f0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
2ba00 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
2ba10 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
2ba20 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
2ba30 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
2ba40 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2ba50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2ba60 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
2ba70 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
2ba80 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
2ba90 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
2baa0 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
2bab0 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
2bac0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
2bad0 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
2bae0 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
2baf0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
2bb00 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
2bb10 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
2bb20 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
2bb30 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
2bb40 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
2bb50 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2bb60 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2bb70 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
2bb80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2bb90 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2bba0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2bbb0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2bbc0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2bbd0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2bbe0 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2bbf0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2bc00 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2bc10 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2bc20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2bc30 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2bc40 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2bc50 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2bc60 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2bc70 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2bc80 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2bc90 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2bca0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2bcb0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2bcc0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2bcd0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2bce0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2bcf0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2bd00 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2bd10 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2bd20 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2bd30 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2bd40 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2bd50 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2bd60 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2bd70 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2bd80 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2bd90 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2bda0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2bdb0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2bdc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2bdd0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2bde0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2bdf0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2be00 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2be10 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2be20 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2be30 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2be40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2be50 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2be60 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2be70 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2be80 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2be90 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2bea0 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2beb0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2bec0 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2bed0 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2bee0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2bef0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2bf00 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2bf10 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2bf20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2bf30 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2bf40 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2bf50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bf60 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2bf70 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2bf80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2bf90 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2bfa0 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2bfb0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2bfc0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2bfd0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2bfe0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2bff0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2c000 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2c010 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2c020 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2c030 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2c040 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2c050 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2c060 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2c070 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2c080 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2c090 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2c0a0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2c0b0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2c0c0 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2c0d0 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2c0e0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2c0f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2c100 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2c110 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2c120 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2c130 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2c140 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2c150 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2c160 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2c170 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2c180 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2c190 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2c1a0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2c1b0 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2c1c0 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2c1d0 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2c1e0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2c1f0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2c200 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2c210 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2c220 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2c230 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2c240 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2c250 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2c260 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2c270 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2c280 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2c290 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2c2a0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2c2b0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2c2c0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2c2d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2c2e0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2c2f0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2c300 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2c310 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2c320 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2c330 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2c340 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2c350 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2c360 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2c370 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2c380 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2c390 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2c3a0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2c3b0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2c3c0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2c3d0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2c3e0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2c3f0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2c400 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2c410 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2c420 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2c430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2c440 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2c450 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2c460 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c470 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2c480 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2c490 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2c4a0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2c4b0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2c4c0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2c4d0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2c4e0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2c4f0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2c500 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c510 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2c520 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2c530 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
2c540 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2c550 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c560 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2c570 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2c580 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2c590 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2c5a0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2c5b0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2c5c0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
2c5d0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
2c5e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c5f0 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
2c600 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
2c610 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2c620 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
2c630 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
2c640 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
2c650 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
2c660 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
2c670 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
2c680 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2c690 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
2c6a0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2c6b0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
2c6c0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
2c6d0 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
2c6e0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2c6f0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
2c700 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2c710 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
2c720 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
2c730 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2c740 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2c750 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
2c760 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
2c770 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2c780 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
2c790 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
2c7a0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
2c7b0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
2c7c0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
2c7d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
2c7e0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2c7f0 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
2c800 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
2c810 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
2c820 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
2c830 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
2c840 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
2c850 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
2c860 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
2c870 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
2c880 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
2c890 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
2c8a0 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
2c8b0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2c8c0 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
2c8d0 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
2c8e0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
2c8f0 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
2c900 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
2c910 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
2c920 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
2c930 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
2c940 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
2c950 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
2c960 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
2c970 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
2c980 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
2c990 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
2c9a0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
2c9b0 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
2c9c0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
2c9d0 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
2c9e0 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
2c9f0 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
2ca00 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
2ca10 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
2ca20 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2ca30 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2ca40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2ca50 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2ca60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2ca70 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2ca80 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2ca90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2caa0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2cab0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
2cac0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2cad0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2cae0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2caf0 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2cb00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2cb10 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2cb20 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2cb30 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2cb40 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2cb50 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2cb60 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2cb70 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2cb80 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2cb90 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2cba0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2cbb0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2cbc0 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2cbd0 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2cbe0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2cbf0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2cc00 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2cc10 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2cc20 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2cc30 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2cc40 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2cc50 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2cc60 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2cc70 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2cc80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2cc90 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2cca0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2ccb0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2ccc0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2ccd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cce0 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2ccf0 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2cd00 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2cd10 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2cd20 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2cd30 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2cd40 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2cd50 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2cd60 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2cd70 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2cd80 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2cd90 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2cda0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2cdb0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2cdc0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2cdd0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2cde0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2cdf0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2ce00 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2ce10 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2ce20 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2ce30 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2ce40 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2ce50 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2ce60 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2ce70 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2ce80 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2ce90 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2cea0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2ceb0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2cec0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2ced0 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2cee0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2cef0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2cf00 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2cf10 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2cf20 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2cf30 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2cf40 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2cf50 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2cf60 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2cf70 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2cf80 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2cf90 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2cfa0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2cfb0 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2cfc0 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2cfd0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2cfe0 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2cff0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2d000 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2d010 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2d020 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2d030 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2d040 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
2d050 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2d060 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2d070 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
2d080 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
2d090 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
2d0a0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2d0b0 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
2d0c0 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
2d0d0 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
2d0e0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2d0f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2d100 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
2d110 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
2d120 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
2d130 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
2d140 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2d150 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
2d160 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
2d170 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
2d180 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
2d190 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
2d1a0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
2d1b0 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
2d1c0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2d1d0 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
2d1e0 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
2d1f0 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
2d200 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
2d210 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2d220 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
2d230 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
2d240 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
2d250 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
2d260 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
2d270 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
2d280 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2d290 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2d2a0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
2d2b0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
2d2c0 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
2d2d0 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
2d2e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
2d2f0 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
2d300 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2d310 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
2d320 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
2d330 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
2d340 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2d350 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
2d360 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
2d370 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
2d380 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
2d390 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
2d3a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2d3b0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
2d3c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d3d0 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
2d3e0 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
2d3f0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2d400 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
2d410 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2d420 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
2d430 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
2d440 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
2d450 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
2d460 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
2d470 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
2d480 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
2d490 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
2d4a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d4b0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
2d4c0 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
2d4d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d4e0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
2d4f0 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
2d500 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
2d510 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2d520 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
2d530 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
2d540 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
2d550 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
2d560 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2d570 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
2d580 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
2d590 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
2d5a0 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
2d5b0 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
2d5c0 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
2d5d0 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
2d5e0 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
2d5f0 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
2d600 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d610 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
2d620 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
2d630 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
2d640 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
2d650 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2d660 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
2d670 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
2d680 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
2d690 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2d6a0 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
2d6b0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2d6c0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
2d6d0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2d6e0 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
2d6f0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
2d700 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
2d710 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
2d720 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
2d730 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
2d740 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
2d750 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
2d760 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2d770 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
2d780 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
2d790 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
2d7a0 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
2d7b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2d7c0 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
2d7d0 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
2d7e0 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
2d7f0 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
2d800 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
2d810 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
2d820 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
2d830 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
2d840 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
2d850 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
2d860 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
2d870 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2d880 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
2d890 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
2d8a0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
2d8b0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
2d8c0 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
2d8d0 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
2d8e0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2d8f0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2d900 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
2d910 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
2d920 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
2d930 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
2d940 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
2d950 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
2d960 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2d970 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2d980 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
2d990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2d9a0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2d9b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
2d9c0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
2d9d0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
2d9e0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2d9f0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
2da00 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2da10 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
2da20 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
2da30 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
2da40 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
2da50 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
2da60 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2da70 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
2da80 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
2da90 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
2daa0 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
2dab0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2dac0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2dad0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2dae0 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
2daf0 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
2db00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2db10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2db20 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
2db30 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
2db40 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2db50 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
2db60 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
2db70 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
2db80 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
2db90 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
2dba0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2dbb0 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
2dbc0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2dbd0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2dbe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2dbf0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2dc00 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2dc10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2dc20 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2dc30 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2dc40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2dc50 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2dc60 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
2dc70 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2dc80 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
2dc90 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2dca0 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
2dcb0 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
2dcc0 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
2dcd0 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
2dce0 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
2dcf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
2dd00 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
2dd10 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
2dd20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
2dd30 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
2dd40 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
2dd50 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
2dd60 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2dd70 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
2dd80 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
2dd90 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2dda0 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
2ddb0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2ddc0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2ddd0 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
2dde0 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
2ddf0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2de00 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2de10 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
2de20 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2de30 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
2de40 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
2de50 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2de60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2de70 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
2de80 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
2de90 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
2dea0 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
2deb0 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
2dec0 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
2ded0 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
2dee0 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
2def0 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
2df00 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
2df10 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
2df20 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2df30 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2df40 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2df50 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
2df60 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
2df70 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2df80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2df90 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
2dfa0 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
2dfb0 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
2dfc0 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
2dfd0 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
2dfe0 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
2dff0 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
2e000 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
2e010 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
2e020 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2e030 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2e040 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
2e050 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
2e060 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
2e070 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
2e080 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
2e090 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2e0a0 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
2e0b0 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
2e0c0 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
2e0d0 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
2e0e0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
2e0f0 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
2e100 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
2e110 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
2e120 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
2e130 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
2e140 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
2e150 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
2e160 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
2e170 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
2e180 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
2e190 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
2e1a0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
2e1b0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2e1c0 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
2e1d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
2e1e0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
2e1f0 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
2e200 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2e210 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
2e220 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2e230 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
2e240 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
2e250 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
2e260 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
2e270 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
2e280 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
2e290 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
2e2a0 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
2e2b0 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
2e2c0 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
2e2d0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2e2e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
2e2f0 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
2e300 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  set" interface..
2e310 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2e320 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
2e330 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
2e340 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
2e350 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
2e360 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
2e370 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
2e380 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
2e390 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
2e3a0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2e3b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2e3c0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
2e3d0 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
2e3e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2e3f0 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
2e400 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
2e410 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e420 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
2e430 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
2e440 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
2e450 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2e460 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
2e470 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
2e480 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
2e490 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
2e4a0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2e4b0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2e4c0 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
2e4d0 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
2e4e0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2e4f0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2e500 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
2e510 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2e520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2e530 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
2e540 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2e550 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
2e560 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
2e570 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
2e580 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
2e590 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2e5a0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
2e5b0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2e5c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2e5d0 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
2e5e0 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
2e5f0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
2e600 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2e610 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
2e620 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
2e630 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
2e640 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
2e650 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2e660 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
2e670 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
2e680 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
2e690 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2e6a0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
2e6b0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
2e6c0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2e6d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2e6e0 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
2e6f0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2e700 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
2e710 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
2e720 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
2e730 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2e740 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
2e750 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2e760 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2e770 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2e780 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
2e790 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
2e7a0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2e7b0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
2e7c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2e7d0 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
2e7e0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2e7f0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2e800 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e810 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
2e820 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2e830 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
2e840 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2e850 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
2e860 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
2e870 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
2e880 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
2e890 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
2e8a0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2e8b0 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
2e8c0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
2e8d0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
2e8e0 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
2e8f0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
2e900 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
2e910 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2e920 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2e930 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
2e940 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
2e950 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
2e960 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
2e970 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
2e980 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
2e990 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
2e9a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
2e9b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e9c0 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
2e9d0 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
2e9e0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2e9f0 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
2ea00 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
2ea10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2ea20 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
2ea30 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2ea40 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
2ea50 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2ea60 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
2ea70 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2ea80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ea90 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2eaa0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2eab0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2eac0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2ead0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2eae0 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
2eaf0 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2eb00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2eb10 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2eb20 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2eb30 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
2eb40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2eb50 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2eb60 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2eb70 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2eb80 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2eb90 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
2eba0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2ebb0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2ebc0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2ebd0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
2ebe0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2ebf0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2ec00 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2ec10 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2ec20 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2ec30 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2ec40 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
2ec50 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
2ec60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2ec70 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
2ec80 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2ec90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2eca0 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
2ecb0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2ecc0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2ecd0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2ece0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2ecf0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2ed00 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
2ed10 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2ed20 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
2ed30 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2ed40 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
2ed50 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2ed60 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2ed70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2ed80 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2ed90 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2eda0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2edb0 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
2edc0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2edd0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2ede0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2edf0 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
2ee00 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2ee10 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2ee20 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2ee30 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2ee40 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2ee50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ee60 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
2ee70 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
2ee80 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2ee90 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2eea0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2eeb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2eec0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
2eed0 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
2eee0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
2eef0 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
2ef00 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
2ef10 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
2ef20 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2ef30 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2ef40 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ef50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2ef60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
2ef70 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
2ef80 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
2ef90 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
2efa0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2efb0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
2efc0 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
2efd0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2efe0 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
2eff0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f000 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
2f010 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
2f020 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
2f030 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
2f040 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
2f050 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
2f060 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
2f070 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2f080 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
2f090 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2f0a0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2f0b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2f0c0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
2f0d0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2f0e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2f0f0 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
2f100 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f110 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
2f120 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2f130 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2f140 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
2f150 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
2f160 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
2f170 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
2f180 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2f190 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2f1a0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2f1b0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2f1c0 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
2f1d0 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
2f1e0 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
2f1f0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2f200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2f210 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
2f220 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2f230 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2f240 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
2f250 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2f260 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2f270 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2f280 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
2f290 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
2f2a0 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
2f2b0 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
2f2c0 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
2f2d0 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
2f2e0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
2f2f0 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
2f300 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
2f310 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2f320 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
2f330 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
2f340 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
2f350 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
2f360 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
2f370 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
2f380 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
2f390 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
2f3a0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
2f3b0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2f3c0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2f3d0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
2f3e0 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
2f3f0 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
2f400 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
2f410 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
2f420 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2f430 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2f440 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
2f450 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2f460 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2f470 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2f480 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
2f490 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2f4a0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
2f4b0 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
2f4c0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
2f4d0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2f4e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
2f4f0 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
2f500 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2f510 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2f520 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2f530 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
2f540 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
2f550 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2f560 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
2f570 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2f580 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
2f590 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2f5a0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2f5b0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2f5c0 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
2f5d0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2f5e0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2f5f0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
2f600 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
2f610 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2f620 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
2f630 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2f640 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2f650 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2f660 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2f670 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2f680 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
2f690 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2f6a0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2f6b0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2f6c0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2f6d0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2f6e0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2f6f0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
2f700 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
2f710 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
2f720 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
2f730 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
2f740 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
2f750 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
2f760 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
2f770 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2f780 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
2f790 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2f7a0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
2f7b0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2f7c0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2f7d0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
2f7e0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
2f7f0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2f800 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
2f810 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
2f820 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
2f830 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
2f840 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
2f850 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
2f860 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
2f870 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
2f880 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
2f890 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
2f8a0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
2f8b0 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
2f8c0 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
2f8d0 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
2f8e0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
2f8f0 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
2f900 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
2f910 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
2f920 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
2f930 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
2f940 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
2f950 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
2f960 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
2f970 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2f980 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
2f990 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2f9a0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
2f9b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f9c0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
2f9d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f9e0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
2f9f0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
2fa00 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2fa10 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
2fa20 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
2fa30 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
2fa40 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
2fa50 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2fa60 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2fa70 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
2fa80 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
2fa90 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
2faa0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2fab0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2fac0 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
2fad0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
2fae0 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
2faf0 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
2fb00 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
2fb10 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2fb20 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2fb30 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
2fb40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fb50 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
2fb60 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2fb70 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2fb80 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2fb90 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2fba0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2fbb0 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
2fbc0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2fbd0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
2fbe0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
2fbf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fc00 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2fc10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2fc20 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2fc30 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2fc40 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2fc50 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
2fc60 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2fc70 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
2fc80 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
2fc90 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
2fca0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
2fcb0 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
2fcc0 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
2fcd0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
2fce0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
2fcf0 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
2fd00 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
2fd10 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
2fd20 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
2fd30 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
2fd40 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
2fd50 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
2fd60 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
2fd70 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
2fd80 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
2fd90 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
2fda0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
2fdb0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
2fdc0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
2fdd0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
2fde0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
2fdf0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
2fe00 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
2fe10 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
2fe20 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
2fe30 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
2fe40 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
2fe50 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
2fe60 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2fe70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
2fe80 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2fe90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fea0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2feb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2fec0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
2fed0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fee0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2fef0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2ff00 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
2ff10 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2ff20 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ff30 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
2ff40 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
2ff50 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
2ff60 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
2ff70 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
2ff80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ff90 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
2ffa0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2ffb0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
2ffc0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
2ffd0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
2ffe0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
2fff0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
30000 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
30010 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30020 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
30030 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
30040 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
30050 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
30060 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
30070 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
30080 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
30090 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
300a0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
300b0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
300c0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
300d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
300e0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
300f0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
30100 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30110 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
30120 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
30130 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
30140 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
30150 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
30160 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
30170 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
30180 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
30190 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
301a0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
301b0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
301c0 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
301d0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
301e0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
301f0 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
30200 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
30210 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
30220 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
30230 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
30240 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
30250 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
30260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30270 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
30280 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
30290 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
302a0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
302b0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
302c0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
302d0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
302e0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
302f0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
30300 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
30310 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
30320 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
30330 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
30340 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
30350 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
30360 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
30370 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
30380 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
30390 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
303a0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
303b0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
303c0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
303d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
303e0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
303f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
30400 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
30410 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
30420 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30430 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
30440 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
30450 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30460 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
30470 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
30480 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
30490 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
304a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
304b0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
304c0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
304d0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
304e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
304f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30500 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
30510 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
30520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30530 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
30540 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
30550 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
30560 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
30570 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30580 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
30590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
305a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
305b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
305c0 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
305d0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
305e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
305f0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
30600 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
30610 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
30620 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
30630 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30640 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
30650 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
30660 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
30670 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30680 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
30690 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
306a0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
306b0 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
306c0 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
306d0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
306e0 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
306f0 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
30700 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30710 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
30720 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
30730 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
30740 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
30750 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
30760 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
30770 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
30780 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
30790 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
307a0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
307b0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
307c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
307d0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
307e0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
307f0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
30800 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
30810 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
30820 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30830 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
30840 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
30850 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
30860 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
30870 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
30880 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
30890 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
308a0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
308b0 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
308c0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
308d0 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
308e0 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
308f0 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
30900 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
30910 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
30920 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
30930 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
30940 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
30950 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
30960 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
30970 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
30980 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
30990 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
309a0 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
309b0 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
309c0 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
309d0 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
309e0 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
309f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
30a00 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
30a10 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
30a20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
30a30 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
30a40 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
30a50 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
30a60 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
30a70 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
30a80 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
30a90 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
30aa0 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
30ab0 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
30ac0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
30ad0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
30ae0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
30af0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
30b00 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
30b10 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
30b20 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
30b30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
30b40 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
30b50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30b60 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
30b70 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
30b80 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
30b90 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
30ba0 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
30bb0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
30bc0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
30bd0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
30be0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
30bf0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
30c00 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
30c10 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
30c20 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
30c30 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
30c40 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
30c50 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
30c60 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
30c70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30c80 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
30c90 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
30ca0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
30cb0 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
30cc0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
30cd0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
30ce0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
30cf0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
30d00 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
30d10 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
30d20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
30d30 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
30d40 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
30d50 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
30d60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
30d70 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
30d80 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
30d90 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
30da0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
30db0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
30dc0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
30dd0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
30de0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30df0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
30e00 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
30e10 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
30e20 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
30e30 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
30e40 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
30e50 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
30e60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
30e70 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
30e80 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
30e90 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
30ea0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
30eb0 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
30ec0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
30ed0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
30ee0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30ef0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
30f00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
30f10 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
30f20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30f30 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
30f40 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
30f50 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
30f60 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
30f70 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
30f80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
30f90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30fa0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
30fb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
30fc0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30fd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
30fe0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
30ff0 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
31000 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
31010 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
31020 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
31030 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
31040 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
31050 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
31060 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
31070 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
31080 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
31090 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
310a0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
310b0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
310c0 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
310d0 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
310e0 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
310f0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
31100 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
31110 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
31120 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
31130 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
31140 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
31150 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
31160 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
31170 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
31180 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
31190 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
311a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
311b0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
311c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
311d0 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
311e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
311f0 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
31200 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
31210 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
31220 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
31230 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
31240 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31250 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
31260 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
31270 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
31280 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
31290 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
312a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
312b0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
312c0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
312d0 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
312e0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
312f0 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
31300 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
31310 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
31320 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
31330 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
31340 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
31350 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
31360 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
31370 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
31380 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
31390 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
313a0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
313b0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
313c0 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
313d0 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
313e0 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
313f0 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
31400 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
31410 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
31420 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
31430 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
31440 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
31450 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
31460 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
31470 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
31480 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
31490 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
314a0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
314b0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
314c0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
314d0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
314e0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
314f0 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
31500 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
31510 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
31520 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
31530 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
31540 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
31550 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
31560 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
31570 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
31580 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
31590 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
315a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
315b0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
315c0 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
315d0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
315e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
315f0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
31600 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
31610 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
31620 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
31630 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
31640 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73   should set this
31650 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
31660 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
31670 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f  ] if the functio
31680 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
31690 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71   invokes .** [sq
316a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
316b0 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16le()] on an in
316c0 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  put, or [SQLITE_
316d0 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a  UTF16BE] if the.
316e0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
316f0 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74  n invokes [sqlit
31700 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
31710 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
31720 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
31730 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74  UTF16] if [sqlit
31740 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
31750 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b  )] is used, or [
31760 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20  SQLITE_UTF8].** 
31770 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65  otherwise.  ^The
31780 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
31790 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
317a0 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
317b0 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66  mes using.** dif
317c0 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64  ferent preferred
317d0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c   text encodings,
317e0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
317f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
31800 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f  for.** each enco
31810 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  ding..** ^When m
31820 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
31830 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
31840 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
31850 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
31860 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
31870 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
31880 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
31890 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
318a0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
318b0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
318c0 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f  ameter may optio
318d0 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69  nally be ORed wi
318e0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  th [SQLITE_DETER
318f0 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20  MINISTIC].** to 
31900 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20  signal that the 
31910 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c  function will al
31920 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
31930 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65  same result give
31940 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e  n.** the same in
31950 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69  puts within a si
31960 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
31970 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75  nt.  Most SQL fu
31980 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64  nctions are.** d
31990 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
319a0 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e  he built-in [ran
319b0 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74  dom()] SQL funct
319c0 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  ion is an exampl
319d0 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69  e of a.** functi
319e0 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64  on that is not d
319f0 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
31a00 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20  he SQLite query 
31a10 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20  planner is able 
31a20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64  to.** perform ad
31a30 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a  ditional optimiz
31a40 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d  ations on determ
31a50 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  inistic function
31a60 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20  s, so use.** of 
31a70 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  the [SQLITE_DETE
31a80 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20  RMINISTIC] flag 
31a90 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77  is recommended w
31aa0 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  here possible..*
31ab0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
31ac0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
31ad0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
31ae0 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
31af0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
31b00 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
31b10 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
31b20 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
31b30 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
31b40 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
31b50 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
31b60 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
31b70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
31b80 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
31b90 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
31ba0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
31bb0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
31bc0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
31bd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
31be0 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
31bf0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
31c00 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
31c10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31c20 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
31c30 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
31c40 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
31c50 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
31c60 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
31c70 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
31c80 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
31c90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
31ca0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
31cb0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
31cc0 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
31cd0 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
31ce0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
31cf0 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
31d00 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
31d10 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
31d20 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
31d30 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
31d40 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
31d50 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
31d60 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
31d70 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
31d80 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
31d90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31da0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
31db0 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
31dc0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
31dd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
31de0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
31df0 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
31e00 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
31e10 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
31e20 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
31e30 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
31e40 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
31e50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
31e60 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
31e70 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
31e80 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
31e90 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
31ea0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
31eb0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
31ec0 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
31ed0 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
31ee0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
31ef0 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
31f00 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
31f10 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
31f20 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
31f30 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
31f40 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
31f50 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
31f60 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
31f70 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
31f80 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
31f90 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
31fa0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
31fb0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
31fc0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
31fd0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
31fe0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
31ff0 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
32000 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
32010 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
32020 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
32030 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
32040 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
32050 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
32060 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
32070 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
32080 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
32090 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
320a0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
320b0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
320c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
320d0 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
320e0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
320f0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
32100 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
32110 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
32120 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
32130 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
32140 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
32150 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
32160 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
32170 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
32180 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
32190 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
321a0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
321b0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
321c0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
321d0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
321e0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
321f0 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
32200 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
32210 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
32220 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
32230 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
32240 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
32250 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
32260 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
32270 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
32280 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
32290 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
322a0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
322b0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
322c0 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
322d0 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
322e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
322f0 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
32300 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
32310 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
32320 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
32330 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
32340 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
32350 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
32360 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
32370 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
32380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
32390 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
323a0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
323b0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
323c0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
323d0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
323e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
323f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
32400 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
32410 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
32420 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
32430 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
32440 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
32450 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
32460 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
32470 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
32480 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32490 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
324a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
324b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
324c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
324d0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
324e0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
324f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32500 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
32510 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
32520 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
32530 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
32540 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
32550 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
32560 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
32570 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32580 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
32590 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
325a0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
325b0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
325c0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
325d0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
325e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
325f0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
32600 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
32610 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
32620 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
32630 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
32640 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
32650 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
32660 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
32670 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
32680 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
32690 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
326a0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
326b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
326c0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
326d0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
326e0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
326f0 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
32700 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
32710 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
32720 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
32730 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
32740 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
32750 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
32760 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
32770 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
32780 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
32790 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
327a0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
327b0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
327c0 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50       1    /* IMP
327d0 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20  : R-37514-35566 
327e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
327f0 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
32800 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   2    /* IMP: R-
32810 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23  03371-37637 */.#
32820 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
32830 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20  F16BE        3  
32840 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37    /* IMP: R-5197
32850 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69  1-34154 */.#defi
32860 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
32870 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
32880 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
32890 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
328a0 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
328b0 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
328c0 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64  Deprecated */.#d
328d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
328e0 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
328f0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
32900 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
32910 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
32920 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46  3REF: Function F
32930 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lags.**.** These
32940 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
32950 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20  e ORed together 
32960 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
32970 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66  LITE_UTF8 | pref
32980 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
32990 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72  ing] as the four
329a0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
329b0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
329c0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b  e_function()], [
329d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
329e0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  unction16()], or
329f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
32a00 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
32a10 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
32a20 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
32a30 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a  TIC    0x800../*
32a40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
32a50 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
32a60 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
32a70 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
32a80 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
32a90 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
32aa0 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
32ab0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
32ac0 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
32ad0 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
32ae0 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
32af0 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
32b00 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
32b10 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
32b20 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
32b30 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
32b40 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
32b50 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72   To encourage pr
32b60 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f  ogrammers to avo
32b70 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63  id.** these func
32b80 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e  tions, we will n
32b90 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20  ot explain what 
32ba0 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
32bb0 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
32bc0 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
32bd0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
32be0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32bf0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
32c00 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
32c10 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
32c20 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
32c30 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
32c40 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
32c50 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
32c60 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
32c70 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
32c80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
32c90 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
32ca0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
32cb0 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
32cc0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
32cd0 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
32ce0 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
32cf0 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
32d00 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
32d10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
32d20 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
32d30 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
32d40 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20  ,int),.         
32d50 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
32d60 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
32d70 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
32d80 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
32d90 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
32da0 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
32db0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
32dc0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
32dd0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
32de0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
32df0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
32e00 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
32e10 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
32e20 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
32e30 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
32e40 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
32e50 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
32e60 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
32e70 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
32e80 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
32e90 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
32ea0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
32eb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32ec0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
32ed0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32ee0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
32ef0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
32f00 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
32f10 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32f20 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
32f30 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
32f40 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
32f50 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
32f60 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
32f70 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
32f80 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32f90 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
32fa0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
32fb0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32fc0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
32fd0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
32fe0 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
32ff0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
33000 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
33010 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
33020 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
33030 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
33040 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
33050 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
33060 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
33070 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
33080 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
33090 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
330a0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
330b0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
330c0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
330d0 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
330e0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
330f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
33100 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
33110 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
33120 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
33130 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
33140 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
33150 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  at these routine
33160 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
33170 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
33180 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
33190 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
331a0 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
331b0 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
331c0 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
331d0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
331e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
331f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
33200 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
33210 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
33220 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
33230 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
33240 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
33250 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
33260 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33270 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
33280 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
33290 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
332a0 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
332b0 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
332c0 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
332d0 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
332e0 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
332f0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
33300 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
33310 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
33320 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
33330 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
33340 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
33350 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
33360 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
33370 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
33380 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
33390 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
333a0 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
333b0 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
333c0 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
333d0 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
333e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
333f0 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
33400 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
33410 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
33420 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
33430 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
33440 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
33450 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
33460 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
33470 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
33480 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
33490 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
334a0 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
334b0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
334c0 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
334d0 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
334e0 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
334f0 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
33500 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
33510 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
33520 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
33530 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
33540 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
33550 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
33560 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
33570 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
33580 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
33590 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
335a0 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
335b0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
335c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
335d0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
335e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
335f0 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
33600 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
33610 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
33620 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
33630 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
33640 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
33650 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
33660 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
33670 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
33680 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
33690 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
336a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
336b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
336c0 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
336d0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
336e0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
336f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
33700 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
33710 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
33720 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
33730 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
33740 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
33750 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
33760 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
33770 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
33780 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
33790 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
337a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
337b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
337c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
337d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
337e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
337f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
33800 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33810 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
33820 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
33830 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
33840 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
33850 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
33860 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
33870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33880 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
33890 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
338a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
338b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
338c0 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
338d0 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
338e0 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
338f0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
33900 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
33910 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
33920 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
33930 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
33940 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
33950 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
33960 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
33970 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
33980 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
33990 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
339a0 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
339b0 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
339c0 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
339d0 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
339e0 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
339f0 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
33a00 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
33a10 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
33a20 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
33a30 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
33a40 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
33a50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
33a60 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
33a70 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
33a80 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
33a90 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
33aa0 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
33ab0 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
33ac0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33ad0 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
33ae0 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
33af0 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
33b00 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
33b10 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
33b20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
33b30 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
33b40 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
33b50 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
33b60 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
33b70 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
33b80 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
33b90 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
33ba0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
33bb0 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
33bc0 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
33bd0 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
33be0 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
33bf0 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
33c00 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
33c10 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
33c20 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
33c30 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
33c40 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
33c50 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
33c60 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
33c70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
33c80 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33c90 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
33ca0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
33cb0 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72  ter .** when fir
33cc0 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69  st called if N i
33cd0 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  s less than or e
33ce0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
33cf0 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
33d00 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
33d10 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
33d20 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
33d30 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
33d40 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
33d50 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
33d60 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
33d70 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
33d80 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
33d90 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
33da0 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
33db0 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
33dc0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
33dd0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33de0 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
33df0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
33e00 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
33e10 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
33e20 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
33e30 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
33e40 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65  n.)^  Within the
33e50 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
33e60 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72  , it is customar
33e70 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20  y to set.** N=0 
33e80 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  in calls to sqli
33e90 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33ea0 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68  ntext(C,N) so th
33eb0 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c  at no .** pointl
33ec0 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ess memory alloc
33ed0 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a  ations occur..**
33ee0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
33ef0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
33f00 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
33f10 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
33f20 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33f30 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
33f40 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
33f50 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
33f60 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
33f70 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
33f80 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
33f90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
33fa0 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
33fb0 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
33fc0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
33fd0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
33fe0 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
33ff0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
34000 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
34010 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
34020 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
34030 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
34040 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
34050 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
34060 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
34070 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
34080 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
34090 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
340a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
340b0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
340c0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
340d0 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
340e0 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
340f0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
34100 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34110 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
34120 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
34130 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
34140 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
34150 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
34160 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
34170 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
34180 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
34190 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
341a0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
341b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
341c0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
341d0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
341e0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
341f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
34200 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34210 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
34220 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
34230 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
34240 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
34250 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
34260 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34270 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
34280 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
34290 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
342a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
342b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
342c0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
342d0 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
342e0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
342f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
34300 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
34310 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
34320 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
34330 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
34340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34350 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
34360 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
34370 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34380 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
34390 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
343a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
343b0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
343c0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
343d0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
343e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
343f0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c  function..*/.sql
34400 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
34410 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
34420 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34430 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34440 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
34450 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
34460 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
34470 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
34480 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29   (non-aggregate)
34490 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
344a0 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
344b0 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
344c0 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
344d0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
344e0 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
344f0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
34500 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
34510 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
34520 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
34530 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
34540 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
34550 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
34560 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
34570 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20   preserved.  An 
34580 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68  example.** of wh
34590 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62  ere this might b
345a0 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61  e useful is in a
345b0 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
345c0 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20  ion matching.** 
345d0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
345e0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
345f0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
34600 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
34610 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
34620 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
34630 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72   with the patter
34640 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54  n string.  .** T
34650 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  hen as long as t
34660 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
34670 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61  g remains the sa
34680 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69  me,.** the compi
34690 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
346a0 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
346b0 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
346c0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
346d0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
346e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
346f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
34700 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
34710 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34720 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
34730 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
34740 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
34750 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
34760 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
34770 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
34780 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
34790 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
347a0 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74   function. ^If t
347b0 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
347c0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
347d0 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74  d with the funct
347e0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68  ion argument, th
347f0 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  is sqlite3_get_a
34800 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
34810 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ce.** returns a 
34820 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
34830 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34840 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
34850 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20  ,P,X) interface 
34860 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64  saves P as metad
34870 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
34880 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
34890 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
348a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
348b0 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a  .  ^Subsequent.*
348c0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
348d0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
348e0 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f  ,N) return P fro
348f0 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  m the most recen
34900 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  t.** sqlite3_set
34910 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
34920 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65  ) call if the me
34930 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20  tadata is still 
34940 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c  valid or.** NULL
34950 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
34960 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72   has been discar
34970 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65  ded..** ^After e
34980 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
34990 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
349a0 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58  C,N,P,X) where X
349b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
349c0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
349d0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
349e0 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  or function X wi
349f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65  th parameter P e
34a00 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20  xactly.** once, 
34a10 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74  when the metadat
34a20 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a  a is discarded..
34a30 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
34a40 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65  e to discard the
34a50 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79   metadata at any
34a60 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67   time, including
34a70 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77  : <ul>.** <li> w
34a80 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
34a90 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
34aa0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
34ab0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
34ac0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
34ad0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
34ae0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
34af0 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
34b00 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
34b10 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ent, or.** <li> 
34b20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74  when sqlite3_set
34b30 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e  _auxdata() is in
34b40 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  voked again on t
34b50 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65  he same paramete
34b60 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75  r, or.** <li> du
34b70 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
34b80 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  l sqlite3_set_au
34b90 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65  xdata() call whe
34ba0 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20  n a memory .**  
34bb0 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65      allocation e
34bc0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75  rror occurs. </u
34bd0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  l>)^.**.** Note 
34be0 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20  the last bullet 
34bf0 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20  in particular.  
34c00 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58  The destructor X
34c10 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   in .** sqlite3_
34c20 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
34c30 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61  P,X) might be ca
34c40 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  lled immediately
34c50 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20  , before the.** 
34c60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34c70 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
34c80 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48  even returns.  H
34c90 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ence sqlite3_set
34ca0 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68  _auxdata().** sh
34cb0 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e  ould be called n
34cc0 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ear the end of t
34cd0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
34ce0 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74  ementation and t
34cf0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  he.** function i
34d00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
34d10 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e  ould not make an
34d20 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72  y use of P after
34d30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
34d40 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65  auxdata() has be
34d50 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  en called..**.**
34d60 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
34d70 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
34d80 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
34d90 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
34da0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
34db0 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
34dc0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f   compile-time co
34dd0 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69  nstants, includi
34de0 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  ng literal.** va
34df0 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
34e00 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73  ters] and expres
34e10 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66  sions composed f
34e20 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a  rom the same.)^.
34e30 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
34e40 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
34e50 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
34e60 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
34e70 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
34e80 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
34e90 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
34ea0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
34eb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34ec0 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
34ed0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
34ee0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
34ef0 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
34f00 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
34f10 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
34f20 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
34f30 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
34f40 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
34f50 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
34f60 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
34f70 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
34f80 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
34f90 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
34fa0 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
34fb0 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
34fc0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
34fd0 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
34fe0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
34ff0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
35000 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
35010 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
35020 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
35030 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
35040 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
35050 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
35060 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
35070 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
35080 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
35090 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
350a0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
350b0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
350c0 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
350d0 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
350e0 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
350f0 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
35100 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
35110 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
35120 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
35130 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
35140 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
35150 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
35160 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
35170 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
35180 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
35190 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
351a0 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
351b0 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
351c0 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
351d0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
351e0 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
351f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
35200 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
35210 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
35220 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
35230 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
35240 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
35250 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a  SQL Function.**.
35260 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
35270 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
35280 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
35290 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
352a0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
352b0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
352c0 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
352d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
352e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
352f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
35300 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
35310 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
35320 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
35330 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
35340 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
35350 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
35360 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
35370 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
35380 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
35390 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
353a0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
353b0 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
353c0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
353d0 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
353e0 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
353f0 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
35400 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
35410 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
35420 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
35430 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
35440 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
35450 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
35460 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35470 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
35480 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
35490 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
354a0 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
354b0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
354c0 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
354d0 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
354e0 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
354f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
35500 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35510 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
35520 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
35530 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
35540 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35550 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
35560 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
35570 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
35580 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
35590 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
355a0 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
355b0 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
355c0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
355d0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
355e0 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
355f0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
35600 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
35610 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35620 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35630 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
35640 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
35650 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
35660 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
35670 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35680 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
35690 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
356a0 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
356b0 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
356c0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
356d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
356e0 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
356f0 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
35700 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
35710 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
35720 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
35730 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
35740 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
35750 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35760 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
35770 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
35780 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
35790 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
357a0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
357b0 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
357c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
357d0 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
357e0 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
357f0 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
35800 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
35810 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
35820 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
35830 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
35840 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
35850 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
35860 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35870 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
35880 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35890 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
358a0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
358b0 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
358c0 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
358d0 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
358e0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
358f0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
35900 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
35910 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
35920 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
35930 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
35940 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
35950 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
35960 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
35970 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
35980 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
35990 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
359a0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
359b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
359c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
359d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
359e0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
359f0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
35a00 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
35a10 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
35a20 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
35a30 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
35a40 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
35a50 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
35a60 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
35a70 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
35a80 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
35a90 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
35aa0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
35ab0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
35ac0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
35ad0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
35ae0 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
35af0 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
35b00 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
35b10 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
35b20 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
35b30 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
35b40 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
35b50 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
35b60 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
35b70 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
35b80 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
35b90 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
35ba0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
35bb0 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
35bc0 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
35bd0 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
35be0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35bf0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e  rror_toobig() in
35c00 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
35c10 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
35c20 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
35c30 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
35c40 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
35c50 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
35c60 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
35c70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35c80 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e  error_nomem() in
35c90 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
35ca0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
35cb0 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
35cc0 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
35cd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
35ce0 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
35cf0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35d00 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
35d10 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
35d20 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
35d30 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35d40 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35d50 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
35d60 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
35d70 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
35d80 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
35d90 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
35da0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
35db0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
35dc0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
35dd0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
35de0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35df0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
35e00 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
35e10 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
35e20 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
35e30 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
35e40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
35e50 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
35e60 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
35e70 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
35e80 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
35e90 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35ea0 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
35eb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35ec0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
35ed0 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
35ee0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
35ef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35f00 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
35f10 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35f20 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
35f30 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
35f40 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
35f50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35f60 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35f70 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
35f80 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
35f90 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
35fa0 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
35fb0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
35fc0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
35fd0 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
35fe0 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
35ff0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54  pectively..** ^T
36000 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36010 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74 65 72  t_text64() inter
36020 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
36030 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
36040 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  .** application-
36050 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36060 20 74 6f 20 62 65 20 61 20 74 65 78 74 20 73 74   to be a text st
36070 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64  ring in an encod
36080 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69 65 64  ing.** specified
36090 20 62 79 20 74 68 65 20 66 69 66 74 68 20 28 61   by the fifth (a
360a0 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d 65 74  nd last) paramet
360b0 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74 20 62  er, which must b
360c0 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c  e one.** of [SQL
360d0 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
360e0 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49  TE_UTF16], [SQLI
360f0 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
36100 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
36110 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b  ..** ^SQLite tak
36120 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
36130 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
36140 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
36150 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
36160 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
36170 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
36180 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66  terfaces..** ^If
36190 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
361a0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
361b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
361c0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
361d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
361e0 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
361f0 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
36200 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a   2nd parameter.*
36210 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
36220 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
36230 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  er..** ^If the 3
36240 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
36250 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
36260 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
36270 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
36280 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
36290 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
362a0 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
362b0 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
362c0 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
362d0 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
362e0 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
362f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
36300 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
36310 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20  lt.  If the 3rd 
36320 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
36330 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
36340 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68  it.** must be th
36350 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e  e byte offset in
36360 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  to the string wh
36370 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
36380 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20  inator would.** 
36390 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74  appear if the st
363a0 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74  ring where NUL t
363b0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
363c0 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
363d0 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  s occur.** in th
363e0 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79  e string at a by
363f0 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69  te offset that i
36400 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  s less than the 
36410 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64  value of the 3rd
36420 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74  .** parameter, t
36430 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
36440 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f  g string will co
36450 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
36460 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72  ULs and the.** r
36470 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
36480 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f  ions operating o
36490 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65  n strings with e
364a0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
364b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49  undefined..** ^I
364c0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
364d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
364e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
364f0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
36500 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36510 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
36520 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
36530 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
36540 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
36550 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
36560 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
36570 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
36580 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
36590 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
365a0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
365b0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
365c0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
365d0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
365e0 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
365f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
36600 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
36610 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
36620 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
36630 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
36640 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
36650 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
36660 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
36670 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
36680 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
36690 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
366a0 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
366b0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
366c0 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
366d0 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
366e0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
366f0 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
36700 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
36710 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
36720 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
36730 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
36740 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
36750 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
36760 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
36770 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
36780 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
36790 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
367a0 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
367b0 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
367c0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
367d0 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
367e0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
367f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36800 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
36810 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
36820 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
36830 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36840 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
36850 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
36860 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
36870 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36880 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
36890 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
368a0 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
368b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
368c0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
368d0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
368e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
368f0 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
36900 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
36910 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
36920 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
36930 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
36940 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
36950 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
36960 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
36970 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
36980 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20  * ^A [protected 
36990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
369a0 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
369b0 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
369c0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
369d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
369e0 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
369f0 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
36a00 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
36a10 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36a20 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
36a30 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
36a40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
36a50 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
36a60 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
36a70 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
36a80 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
36a90 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
36aa0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36ab0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36ac0 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
36ad0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
36ae0 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
36af0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
36b00 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
36b10 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36b20 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
36b30 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
36b40 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
36b50 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
36b60 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36b70 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  t_blob64(sqlite3
36b80 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20  _context*,const 
36b90 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20  void*,.         
36ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36bb0 20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34    sqlite3_uint64
36bc0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
36bd0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36be0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
36bf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
36c00 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
36c10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36c20 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
36c30 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
36c40 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
36c50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36c60 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
36c70 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36c80 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
36c90 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36ca0 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
36cb0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
36cc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36cd0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
36ce0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
36cf0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36d00 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
36d10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36d20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
36d30 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
36d40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36d50 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
36d60 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
36d70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36d80 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
36d90 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36da0 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
36db0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
36dc0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36dd0 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
36de0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
36df0 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
36e00 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
36e10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36e20 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63  text64(sqlite3_c
36e30 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
36e40 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
36e50 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
36e60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36e70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
36e80 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
36e90 63 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71  coding);.void sq
36ea0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36eb0 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
36ec0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
36ed0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
36ee0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
36ef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36f00 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
36f10 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
36f20 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
36f30 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36f40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36f50 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
36f60 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
36f70 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
36f80 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
36f90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
36fa0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
36fb0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
36fc0 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
36fd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
36fe0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
36ff0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
37000 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37010 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
37020 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
37030 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
37040 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76  tions add, remov
37050 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b  e, or modify a [
37060 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63  collation] assoc
37070 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
37080 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37090 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
370a0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
370b0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
370c0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
370d0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55  collation is a U
370e0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
370f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
37100 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
37110 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
37120 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
37130 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
37140 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
37150 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
37160 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37170 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
37180 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65   ^Collation name
37190 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65  s that compare e
371a0 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74  qual according t
371b0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69  o [sqlite3_strni
371c0 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f  cmp()] are.** co
371d0 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74  nsidered to be t
371e0 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
371f0 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20  .** ^(The third 
37200 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52  argument (eTextR
37210 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  ep) must be one 
37220 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
37230 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
37240 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  > [SQLITE_UTF8],
37250 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
37260 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16LE],.** <l
37270 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
37280 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BE],.** <li> [SQ
37290 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a  LITE_UTF16], or.
372a0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
372b0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a  UTF16_ALIGNED]..
372c0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54  ** </ul>)^.** ^T
372d0 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
372e0 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20  ment determines 
372f0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
37300 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a  strings passed.*
37310 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  * to the collati
37320 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
37330 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e  back, xCallback.
37340 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
37350 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c  _UTF16] and [SQL
37360 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
37370 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54  D] values for eT
37380 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20  extRep.** force 
37390 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54  strings to be UT
373a0 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20  F16 with native 
373b0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
373c0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
373d0 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
373e0 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f   for eTextRep fo
373f0 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20  rces strings to 
37400 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65  begin.** on an e
37410 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73  ven byte address
37420 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
37430 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41  rth argument, pA
37440 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63  rg, is an applic
37450 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
37460 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
37470 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20  d.** through as 
37480 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
37490 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  nt to the collat
374a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
374b0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
374c0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
374d0 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20  , xCallback, is 
374e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
374f0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37500 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c  ion..** ^Multipl
37510 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
37520 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67  tions can be reg
37530 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
37540 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a  e same name but.
37550 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ** with differen
37560 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d  t eTextRep param
37570 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65  eters and SQLite
37580 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65   will use whiche
37590 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ver.** function 
375a0 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61  requires the lea
375b0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
375c0 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  a transformation
375d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61  ..** ^If the xCa
375e0 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
375f0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
37600 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37610 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65  ion is.** delete
37620 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f  d.  ^When all co
37630 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37640 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d  s having the sam
37650 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74  e name are delet
37660 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c  ed,.** that coll
37670 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ation is no long
37680 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  er usable..**.**
37690 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20   ^The collating 
376a0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
376b0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
376c0 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  h a copy of the 
376d0 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61  pArg .** applica
376e0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
376f0 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73  r and with two s
37700 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e  trings in the en
37710 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
37720 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74  .** by the eText
37730 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Rep argument.  T
37740 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
37750 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72  ction must retur
37760 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  n an.** integer 
37770 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65  that is negative
37780 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74  , zero, or posit
37790 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69  ive.** if the fi
377a0 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
377b0 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74  ss than, equal t
377c0 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
377d0 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a  an the second,.*
377e0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
377f0 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
37800 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79  ction must alway
37810 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
37820 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65  e answer.** give
37830 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  n the same input
37840 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  s.  If two or mo
37850 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  re collating fun
37860 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73  ctions are regis
37870 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  tered.** to the 
37880 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e  same collation n
37890 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65  ame (using diffe
378a0 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61  rent eTextRep va
378b0 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a  lues) then all.*
378c0 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65  * must give an e
378d0 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72  quivalent answer
378e0 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69   when invoked wi
378f0 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74  th equivalent st
37900 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f  rings..** The co
37910 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37920 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66   must obey the f
37930 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74  ollowing propert
37940 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73  ies for all.** s
37950 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64  trings A, B, and
37960 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   C:.**.** <ol>.*
37970 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74  * <li> If A==B t
37980 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69  hen B==A..** <li
37990 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d  > If A==B and B=
379a0 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a  =C then A==C..**
379b0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
379c0 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20  THEN B&gt;A..** 
379d0 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61  <li> If A&lt;B a
379e0 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41  nd B&lt;C then A
379f0 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  &lt;C..** </ol>.
37a00 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61  **.** If a colla
37a10 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61  ting function fa
37a20 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61  ils any of the a
37a30 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  bove constraints
37a40 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c   and that.** col
37a50 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37a60 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61  is  registered a
37a70 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  nd used, then th
37a80 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  e behavior of SQ
37a90 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  Lite.** is undef
37aa0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
37ab0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37ac0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
37ad0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
37ae0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37af0 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65  on().** with the
37b00 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74   addition that t
37b10 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
37b20 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
37b30 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20  on pArg when.** 
37b40 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
37b50 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
37b60 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67  d..** ^Collating
37b70 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64   functions are d
37b80 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79  eleted when they
37b90 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
37ba0 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c  by later.** call
37bb0 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  s to the collati
37bc0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
37bd0 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
37be0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
37bf0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
37c00 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  osed using [sqli
37c10 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
37c20 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f  .** ^The xDestro
37c30 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75  y callback is <u
37c40 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20  >not</u> called 
37c50 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74  if the .** sqlit
37c60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37c70 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f  ion_v2() functio
37c80 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63  n fails.  Applic
37c90 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f  ations that invo
37ca0 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  ke.** sqlite3_cr
37cb0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
37cc0 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  2() with a non-N
37cd0 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67  ULL xDestroy arg
37ce0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  ument should .**
37cf0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
37d00 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f  n code and dispo
37d10 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  se of the applic
37d20 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
37d30 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73  er.** themselves
37d40 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70   rather than exp
37d50 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f  ecting SQLite to
37d60 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f   deal with it fo
37d70 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20  r them..** This 
37d80 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  is different fro
37d90 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51  m every other SQ
37da0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
37db0 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e   The inconsisten
37dc0 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74  cy .** is unfort
37dd0 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74  unate but cannot
37de0 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68   be changed with
37df0 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63  out breaking bac
37e00 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61  kwards .** compa
37e10 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
37e20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69  See also:  [sqli
37e30 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37e40 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  eded()] and [sql
37e50 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37e60 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69  eeded16()]..*/.i
37e70 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
37e80 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
37e90 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
37ea0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
37eb0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
37ec0 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
37ed0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
37ee0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37ef0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37f00 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
37f10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37f20 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
37f30 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
37f40 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
37f50 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
37f60 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
37f70 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
37f80 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
37f90 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
37fa0 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
37fb0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
37fc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
37fd0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
37fe0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
37ff0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
38000 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
38010 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
38020 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
38030 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
38040 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
38050 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
38060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
38070 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
38080 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
38090 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67  ^To avoid having
380a0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
380b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
380c0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
380d0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
380e0 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
380f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
38100 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
38110 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
38120 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
38130 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f  tion] to be invo
38140 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  ked whenever an 
38150 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
38160 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
38170 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
38180 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  ** ^If the funct
38190 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
381a0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
381b0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
381c0 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
381d0 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
381e0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
381f0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
38200 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
38210 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
38220 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20  d in UTF-8. ^If 
38230 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
38240 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
38250 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d  used,.** the nam
38260 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73  es are passed as
38270 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
38280 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
38290 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  rder..** ^A call
382a0 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
382b0 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65  ion replaces the
382c0 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74   existing collat
382d0 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62  ion-needed callb
382e0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65  ack..**.** ^(Whe
382f0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
38300 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
38310 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
38320 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
38330 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
38340 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
38350 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
38360 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
38370 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
38380 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
38390 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
383a0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
383b0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
383c0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
383d0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
383e0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
383f0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
38400 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
38410 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
38420 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
38430 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
38440 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
38450 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
38460 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
38470 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
38480 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
38490 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
384a0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
384b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  .)^.**.** The ca
384c0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
384d0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
384e0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
384f0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
38500 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
38510 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
38520 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
38530 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
38540 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
38550 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
38560 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
38570 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
38580 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
38590 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
385a0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
385b0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
385c0 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
385d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
385e0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
385f0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
38600 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
38610 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
38620 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
38630 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
38640 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
38650 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
38660 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
38670 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
38680 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
38690 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
386a0 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
386b0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
386c0 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
386d0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
386e0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
386f0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
38700 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
38710 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
38720 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  */.int sqlite3_k
38730 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
38740 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
38750 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
38760 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
38770 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
38780 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
38790 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
387a0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
387b0 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  key_v2(.  sqlite
387c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
387d0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
387e0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
387f0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  ed */.  const ch
38800 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
38810 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
38820 66 20 74 68 65 20 64