/ Hex Artifact Content
Login

Artifact af7fb18afaacfde7db4ab70903785dbd7a91e851:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  y are supported 
07d0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
07e0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
07f0: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
0800: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
0810: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
0820: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
0830: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
0840: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
0850: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
0860: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
0870: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
0880: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
0890: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
08a0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
08b0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
08c0: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
08d0: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
08e0: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
08f0: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
0900: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
0910: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
0920: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
0930: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
0940: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
0950: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
0960: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
0970: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
0980: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0990: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
09a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
09b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
09c0: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
09d0: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
09e0: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
09f0: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
0a00: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
0a10: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
0a20: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0a30: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
0a40: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0a50: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
0a60: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a70: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
0a80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0a90: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
0aa0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0ab0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
0ac0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ad0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0ae0: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
0af0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
0b00: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
0b10: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0b20: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0b30: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
0b40: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
0b50: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
0b60: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0b70: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
0b80: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
0b90: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
0ba0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0bb0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
0bc0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0bd0: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
0be0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bf0: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
0c00: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
0c10: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
0c20: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
0c30: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0c40: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0c50: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
0c60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
0c70: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
0c80: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
0c90: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0ca0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
0cb0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
0cc0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
0cd0: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
0ce0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
0cf0: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
0d00: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
0d10: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
0d20: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
0d30: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
0d40: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
0d50: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
0d60: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
0d70: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
0d80: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
0d90: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
0da0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
0db0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
0dc0: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
0dd0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
0de0: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
0df0: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
0e00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0e10: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
0e20: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
0e30: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
0e40: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
0e50: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
0e60: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
0e70: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
0e80: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
0e90: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
0ea0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
0eb0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
0ec0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
0ed0: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
0ee0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
0ef0: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
0f00: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
0f10: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
0f20: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
0f30: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
0f40: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0f50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0f60: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
0f70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0f80: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
0f90: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
0fa0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
0fb0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
0fc0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
0fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
0fe0: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
0ff0: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69  "--VERS--".#defi
1000: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1010: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49  N_NUMBER --VERSI
1020: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66  ON-NUMBER--.#def
1030: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1040: 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55  E_ID      "--SOU
1050: 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a  RCE-ID--"../*.**
1060: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1070: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
1080: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
1090: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10a0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
10b0: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
10c0: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
10d0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
10e0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
10f0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1100: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1110: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1120: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1130: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1140: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
1150: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
1160: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1170: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
1180: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
1190: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11a0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
11b0: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
11c0: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
11d0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
11e0: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
11f0: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1200: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1210: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1220: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1230: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1240: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
1250: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
1260: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
1270: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
1280: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
1290: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12b0: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
12c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
12d0: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
12e0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
12f0: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1300: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1310: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1320: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1330: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1340: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
1350: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
1360: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1370: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1380: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1390: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13a0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
13b0: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
13c0: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
13d0: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
13e0: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
13f0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1400: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1410: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1420: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1430: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1440: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
1450: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1460: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
1470: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
1480: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1490: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14a0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
14b0: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
14c0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
14d0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
14e0: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
14f0: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1510: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1520: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1530: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1540: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
1550: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
1560: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
1570: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
1580: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
1590: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15a0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
15b0: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
15c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
15d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
15e0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
15f0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1600: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1610: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1620: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ()]..*/.SQLITE_E
1630: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
1640: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1650: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
1660: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1670: 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20  on(void);.const 
1680: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1690: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e  urceid(void);.in
16a0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
16b0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
16c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16d0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
16e0: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
16f0: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1700: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1710: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1720: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1730: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1740: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1750: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1760: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
1770: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
1780: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1790: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
17a0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
17b0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
17c0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
17d0: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
17e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
17f0: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1800: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1810: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1820: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1830: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1840: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1850: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1860: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
1870: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
1880: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
18a0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
18b0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
18c0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
18d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
18e0: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
18f0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1900: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1910: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1920: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1930: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1940: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1950: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1960: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1970: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1980: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
19a0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
19b0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19c0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
19d0: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
19e0: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
19f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1a00: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1a10: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1a20: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1a30: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1a40: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1a50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a60: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1a80: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1a90: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1aa0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1ab0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1ac0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1ad0: 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65  DIAGS.int sqlite
1ae0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1af0: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20  used(const char 
1b00: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73  *zOptName);.cons
1b10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1b20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1b40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1b60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1b70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1b80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1b90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1ba0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1bb0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1bc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1bd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1be0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1bf0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1c00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1c10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1c20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1c30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1c40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1c50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1c60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1c70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1c80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1c90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ca0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1cb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1cc0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1cd0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ce0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1cf0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1d10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1d20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1d30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1d40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1d50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1d60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1d70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1d80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1d90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1da0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1db0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1dc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1dd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1de0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1df0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1e00: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1e10: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1e20: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1e30: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1e40: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1e50: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
1e60: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
1e70: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
1e80: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
1e90: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1ea0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
1eb0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
1ec0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1ed0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
1ee0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
1ef0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
1f00: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
1f10: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
1f20: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
1f30: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f40: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
1f50: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
1f60: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
1f70: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
1f80: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
1f90: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1fa0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
1fb0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1fc0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
1fd0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fe0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
1ff0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2000: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2010: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2020: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2030: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2040: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2050: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2060: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2080: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
20a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
20b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
20c0: 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65  IALIZED].  ^(The
20d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
20e0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
20f0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
2100: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
2110: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2120: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
2130: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
2140: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
2150: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
2160: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
2170: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
2180: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
2190: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
21a0: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
21b0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
21c0: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
21d0: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
21e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
21f0: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
2200: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
2210: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2220: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2230: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  rmation..*/.int 
2240: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2250: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
2260: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
2270: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
2280: 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  andle.** KEYWORD
2290: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
22a0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
22b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
22c0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
22d0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
22e0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
22f0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
2300: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
2310: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
2320: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
2330: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
2340: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
2350: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
2360: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
2370: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
2380: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2390: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
23a0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
23b0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
23c0: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
23d0: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
23e0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
23f0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2400: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72  3_close_v2()] ar
2410: 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  e its destructor
2420: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  s.  There are ma
2430: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65  ny other.** inte
2440: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
2450: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2460: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2470: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2480: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
2490: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
24a0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
24b0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
24c0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
24d0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
24e0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
24f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
2500: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
2510: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
2520: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a  Integer Types.**
2530: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
2540: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
2550: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
2560: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
2570: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
2580: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
2590: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
25a0: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
25b0: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
25c0: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
25d0: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
25e0: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
25f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
2600: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
2610: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
2620: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69  rred type defini
2630: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71  tions..** The sq
2640: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
2650: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2660: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  es are supported
2670: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
2680: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
2690: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
26a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
26b0: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  nd sqlite_int64 
26c0: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
26d0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a  integer values.*
26e0: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33  * between -92233
26f0: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61  72036854775808 a
2700: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35  nd +922337203685
2710: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76  4775807 inclusiv
2720: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2730: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73  te3_uint64 and s
2740: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2750: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2760: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20  eger values .** 
2770: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31  between 0 and +1
2780: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31  8446744073709551
2790: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a  615 inclusive..*
27a0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
27b0: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
27c0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
27d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
27e0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
27f0: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
2800: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2810: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
2820: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2830: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2840: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2850: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2860: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2870: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2880: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2890: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
28a0: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
28b0: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
28c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
28d0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
28e0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28f0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2900: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2910: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2920: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2930: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2940: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2950: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2960: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2970: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2980: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2990: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
29a0: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
29b0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
29c0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
29d0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
29e0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
29f0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2a00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2a10: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2a20: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
2a30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2a40: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2a50: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2a60: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2a70: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2a80: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2a90: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2aa0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ab0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2ac0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2ad0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2ae0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2af0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2b00: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2b10: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2b20: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2b30: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2b40: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2b50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b60: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2b70: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2b80: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2b90: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ba0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2bb0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2bc0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2bd0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2c00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2c10: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2c20: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2c30: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2c40: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2c50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2c60: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2c70: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2c80: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2c90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ca0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2cb0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2cc0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2cd0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ce0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2cf0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2d00: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2d10: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2d20: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2d30: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2d40: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2d50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2d60: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2d70: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2d80: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2d90: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2da0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2db0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2dc0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2dd0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2de0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2df0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2e00: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
2e10: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e20: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2e30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e40: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
2e50: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
2e60: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
2e70: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
2e80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
2e90: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
2ea0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
2eb0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
2ec0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
2ed0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
2ee0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
2ef0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
2f00: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
2f10: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
2f20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
2f30: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f50: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2f60: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
2f70: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f80: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
2f90: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
2fa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
2fb0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
2fc0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
2fd0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
2fe0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
2ff0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3000: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3010: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3020: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3030: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3040: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3050: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3060: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3070: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3080: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3090: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
30a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
30b0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
30c0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
30d0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
30e0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
30f0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3100: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3110: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3120: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3130: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3140: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3150: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3160: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3170: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
31a0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
31b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
31c0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
31d0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
31e0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
31f0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3200: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3210: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3220: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3230: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3240: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3250: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3260: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3270: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3280: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3290: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
32a0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
32b0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
32c0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
32d0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
32e0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
32f0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3300: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3310: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3320: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3330: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3340: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3350: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3360: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3370: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3380: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
3390: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
33a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
33b0: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
33c0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
33d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
33f0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
3400: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
3410: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3420: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3430: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3440: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3450: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3460: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3470: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3480: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3490: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
34a0: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
34b0: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
34c0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
34d0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
34e0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
34f0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
3500: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
3510: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3520: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3530: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3540: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3550: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3580: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3590: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
35a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
35b0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
35c0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
35d0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
35e0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
35f0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
3600: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3610: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3620: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3630: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3640: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3650: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3660: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3670: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3680: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3690: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
36a0: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
36b0: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
36c0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
36d0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
36e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
36f0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3700: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3710: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3720: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3730: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3740: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3750: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3760: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3770: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3780: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3790: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
37a0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
37b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
37c0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
37d0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
37e0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
37f0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3800: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3810: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3820: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3830: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3840: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3850: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3860: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3870: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3880: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3890: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
38a0: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
38b0: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
38c0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
38d0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
38e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
38f0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3900: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3910: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3920: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3930: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3950: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3960: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3970: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3980: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3990: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
39a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
39b0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
39c0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
39d0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
39e0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
39f0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3a00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3a10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3a20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3a30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3a40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3a50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3a60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3a70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3a80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3a90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3aa0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3ab0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3ac0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3ad0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ae0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3af0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3b00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3b20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3b30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3b40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3b50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3b60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3b70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3b80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3b90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ba0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3bb0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3bc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3bd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3be0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3c10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3c20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3c30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3c40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3c50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3c60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3c70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3c80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3c90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ca0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3cb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3cc0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3cd0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ce0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3cf0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3d00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3d10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3d20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3d30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3d40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3d50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3d60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3d70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3d80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3d90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3da0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3db0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3dc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3dd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3de0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3df0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
3e00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e10: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
3e20: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3e30: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3e40: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
3e50: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3e70: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3e80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e90: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
3ea0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3eb0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3ec0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3ed0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3ef0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3f00: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3f10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3f20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3f30: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3f40: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3f50: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3f60: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3f70: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3f80: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3f90: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3fa0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3fb0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
3fc0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
3fd0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ff0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4000: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4010: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4040: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4050: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4060: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4070: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4080: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4090: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
40d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
40e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
40f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4110: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4120: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4130: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4140: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4150: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4160: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4170: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4180: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4190: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
41e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
41f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4200: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4210: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4220: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4230: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4240: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4250: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4260: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4270: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4280: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4290: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
42a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
42b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
42c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
42d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
42e0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
42f0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
4300: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4310: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4320: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4330: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4340: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4350: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4360: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4370: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4380: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4390: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
43a0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
43b0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
43c0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
43f0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4400: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4420: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4430: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4440: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4450: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4460: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4470: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4480: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
44b0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
44c0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
44d0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
44e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
44f0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4500: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4510: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4520: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4540: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4550: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4560: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4570: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4580: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4590: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
45a0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
45b0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
45e0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
45f0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4600: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4610: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4620: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4630: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4640: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4650: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4660: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4670: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4680: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4690: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
46a0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
46b0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
46c0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
46d0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
46e0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
46f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4700: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4710: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4720: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4730: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4740: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4750: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4760: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4770: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4780: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4790: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
47a0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
47b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47c0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
47d0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
47e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
47f0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4800: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4810: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4820: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4830: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4840: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4850: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4860: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4880: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4890: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
48a0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
48b0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
48c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
48d0: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
48e0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
48f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4900: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4910: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4920: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4930: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4950: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4960: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4970: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4980: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
49a0: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
49b0: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
49c0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
49d0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
49e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49f0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4a00: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4a10: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4a20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4a30: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4a40: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4a50: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4a60: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4a70: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4a80: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4a90: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4aa0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4ab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ac0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ad0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4ae0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4af0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4b00: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4b10: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4b20: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4b30: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4b40: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b50: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b60: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4b70: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4b80: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4b90: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4ba0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4bb0: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4bc0: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4bd0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4be0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4bf0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4c00: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4c10: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4c20: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4c30: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4c40: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4c50: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4c60: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4c70: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4c80: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4c90: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4ca0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4cb0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4cc0: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4cd0: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4ce0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4cf0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4d00: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4d10: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4d20: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4d30: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4d40: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65  ese [extended re
4d50: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
4d60: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4d70: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4d80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4d90: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4da0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4db0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4dc0: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f  codes()] API.  O
4dd0: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20  r, the extended 
4de0: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
4df0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
4e00: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  r can be obtaine
4e10: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
4e20: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
4e30: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  code()]..*/.#def
4e40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e50: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
4e60: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e70: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
4e80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4e90: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
4ea0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4eb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
4ec0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
4ed0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
4ee0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4ef0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
4f00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
4f10: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
4f20: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f30: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
4f50: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
4f60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f70: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
4f90: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
4fa0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
4fb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
4fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fe0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
4ff0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5000: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
5010: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5020: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
5030: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5040: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
5050: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5060: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5070: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5080: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5090: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
50b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
50d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
50f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5100: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
5110: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5120: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
5130: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5140: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
5150: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5160: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5170: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5180: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5190: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
51a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
51b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51c0: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
51d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
51f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5200: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
5210: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5220: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
5230: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5240: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
5250: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
5260: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
5270: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5280: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
5290: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
52b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
52c0: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
52d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
52f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5300: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
5310: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5320: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
5330: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5340: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
5350: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5360: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
5390: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
53b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53c0: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
53d0: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
53e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
53f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5400: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
5410: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5420: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
5430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5440: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
5450: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5460: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
5470: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5480: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
5490: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
54a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
54b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54c0: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
54d0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
54e0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
54f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5500: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
5510: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5520: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
5530: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5540: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f  ITE_BUSY_SNAPSHO
5550: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  T           (SQL
5560: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32  ITE_BUSY   |  (2
5570: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5580: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5590: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
55a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
55b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
55c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
55d0: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
55e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
55f0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5600: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5610: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20  N_FULLPATH      
5620: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5630: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  N | (3<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5650: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  PEN_CONVPATH    
5660: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5670: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  PEN | (4<<8)).#d
5680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
5690: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
56a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
56b0: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
56c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
56d0: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
56e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
56f0: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
5720: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5730: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
5740: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5750: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42  E_READONLY_ROLLB
5760: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  ACK       (SQLIT
5770: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c  E_READONLY | (3<
5780: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5790: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d  ITE_READONLY_DBM
57a0: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c  OVED        (SQL
57b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57c0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
57d0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
57e0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
57f0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5800: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5810: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5820: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5830: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5840: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5850: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5860: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5870: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5880: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
58a0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
58b0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
58c0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
58d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58e0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
58f0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5900: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5910: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5920: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5930: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5940: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5950: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5960: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5970: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5980: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5990: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
59a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59b0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
59c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59d0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
59e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
59f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5a00: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5a20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a30: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a40: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a60: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5a70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a80: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
5a90: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5aa0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
5ab0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5ac0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
5ad0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
5ae0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
5af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5b00: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
5b10: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
5b20: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
5b30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
5b40: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
5b50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
5b60: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
5b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
5b80: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
5b90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
5ba0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  TH | (1<<8))../*
5bb0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
5bc0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
5bd0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
5be0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
5bf0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
5c00: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
5c10: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5c20: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5c30: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5c40: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5c50: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5c60: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5c70: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
5c80: 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  hod..*/.#define 
5c90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5ca0: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
5cb0: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66  0000001  /* Ok f
5cc0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5cd0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5cf0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
5d00: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66  0000002  /* Ok f
5d10: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d20: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
5d40: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
5d50: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66  0000004  /* Ok f
5d60: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d70: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
5d90: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
5da0: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20  0000008  /* VFS 
5db0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5dc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
5dd0: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
5de0: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20  0000010  /* VFS 
5df0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f  SQLITE_OPEN_AUTO
5e10: 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30  PROXY        0x0
5e20: 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20  0000020  /* VFS 
5e30: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
5e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5e60: 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66  0000040  /* Ok f
5e70: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5e80: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5e90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f  SQLITE_OPEN_MEMO
5ea0: 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30  RY           0x0
5eb0: 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66  0000080  /* Ok f
5ec0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5ed0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ee0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5ef0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f00: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20  0000100  /* VFS 
5f10: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5f30: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f40: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20  0000200  /* VFS 
5f50: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
5f70: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
5f80: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20  0000400  /* VFS 
5f90: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5fb0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
5fc0: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20  0000800  /* VFS 
5fd0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fe0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5ff0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
6000: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20  0001000  /* VFS 
6010: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6020: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
6030: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
6040: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20  0002000  /* VFS 
6050: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
6070: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
6080: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20  0004000  /* VFS 
6090: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
60a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
60b0: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
60c0: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0008000  /* Ok f
60d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
60e0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
60f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
6100: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
6110: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0010000  /* Ok f
6120: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6130: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6140: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
6150: 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30  EDCACHE      0x0
6160: 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0020000  /* Ok f
6170: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6180: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6190: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
61a0: 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30  ATECACHE     0x0
61b0: 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0040000  /* Ok f
61c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
61d0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
61e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20  SQLITE_OPEN_WAL 
61f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6200: 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20  0080000  /* VFS 
6210: 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65  only */../* Rese
6220: 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20  rved:           
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6240: 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a  00F00000 */../*.
6250: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
6260: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
6270: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
6280: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6290: 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  tics method of t
62a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
62b0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
62c0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
62d0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
62e0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a  vector of these.
62f0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
6300: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
6310: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
6320: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
6330: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
6340: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
6350: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
6360: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6370: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
63a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
63b0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
63c0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
63d0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
63e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
63f0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6400: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6410: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6420: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6430: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6440: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6450: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6460: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6470: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6480: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6490: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
64a0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
64b0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
64c0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
64d0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
64e0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
64f0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6500: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6510: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6520: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6530: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6550: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6560: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6570: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6580: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6590: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
65a0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
65b0: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
65c0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
65d0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
65e0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
65f0: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
6600: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
6610: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
6620: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
6630: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
6640: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
6650: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
6660: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
6670: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
6680: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
6690: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
66a0: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
66b0: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
66c0: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
66d0: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  be unchanged.  T
66e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66f0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6700: 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e  _OPEN.** flag in
6710: 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69  dicate that a fi
6720: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6730: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6740: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6750: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6760: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6770: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6780: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6790: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
67a0: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
67b0: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
67c0: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
67d0: 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65  ivileges..*/.#de
67e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
67f0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6800: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6810: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6830: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6840: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6850: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6860: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6870: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6880: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6890: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
68a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
68b0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
68c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
68d0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
68e0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
68f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6900: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6910: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6920: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6940: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6950: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6970: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6980: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6990: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
69a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69b0: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
69c0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
69d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
69f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6a00: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a10: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6a20: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6a30: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6a40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6a50: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6a60: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a80: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6a90: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6aa0: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6ac0: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
6ad0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a      0x00002000..
6ae0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6af0: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6b00: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
6b10: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
6b20: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6b30: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
6b40: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
6b50: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
6b60: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
6b70: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
6b80: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
6b90: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6ba0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
6bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6bc0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6be0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
6bf0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
6c00: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6c10: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6c20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6c30: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
6c40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6c50: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
6c60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c70: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
6c80: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
6c90: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
6ca0: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
6cb0: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
6cc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6cd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6ce0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6cf0: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6d00: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6d10: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
6d20: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
6d30: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
6d40: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
6d50: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
6d60: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
6d70: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
6d80: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
6d90: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
6da0: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
6db0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
6dc0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
6dd0: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
6de0: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
6df0: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
6e00: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e10: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
6e20: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6e30: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
6e40: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6e50: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
6e60: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6e70: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
6e80: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
6e90: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
6ea0: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
6eb0: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
6ec0: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
6ed0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6ee0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6ef0: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
6f00: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
6f10: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
6f20: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
6f30: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
6f40: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
6f50: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
6f60: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
6f70: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
6f80: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
6f90: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
6fa0: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
6fb0: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
6fc0: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
6fd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6fe0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6ff0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
7000: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
7010: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
7020: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
7030: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
7040: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
7050: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
7060: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
7070: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
7080: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
7090: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
70a0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
70b0: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
70c0: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
70d0: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
70e0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
70f0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7100: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
7110: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
7120: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
7130: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
7140: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
7150: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
7160: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
7170: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
7180: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7190: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
71a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71b0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
71c0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
71d0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
71e0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
71f0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
7200: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7210: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
7220: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
7230: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7240: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
7250: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
7260: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
7270: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
7280: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
7290: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
72a0: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
72b0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
72c0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
72d0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
72e0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
72f0: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
7300: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
7310: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
7320: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
7330: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
7340: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7350: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
7360: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
7370: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
7380: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
7390: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
73a0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
73b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
73c0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
73d0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
73e0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
73f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7400: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
7410: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
7420: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
7430: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7440: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
7450: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
7460: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
7470: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
7480: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7490: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
74a0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
74b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
74c0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
74d0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
74e0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
74f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7500: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
7510: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
7520: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
7530: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
7540: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7550: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
7560: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
7570: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
7580: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
7590: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
75a0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
75b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
75c0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
75d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
75e0: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
75f0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7600: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7610: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
7620: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
7630: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
7640: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
7650: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
7660: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
7670: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7680: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
7690: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
76a0: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
76b0: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
76c0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
76d0: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
76e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
76f0: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
7700: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7710: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
7720: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7730: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
7740: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
7750: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
7760: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
7770: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
7780: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
7790: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
77a0: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
77b0: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
77c0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
77d0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
77e0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
77f0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7800: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
7810: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7820: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
7830: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
7840: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
7850: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
7860: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
7870: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
7880: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
7890: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
78a0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
78b0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
78c0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
78d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
78e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
78f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7900: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7910: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7920: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
7930: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7940: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
7950: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7960: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
7970: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
7980: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
7990: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
79a0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
79b0: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
79c0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
79d0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
79e0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
79f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
7a00: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
7a10: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
7a20: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
7a30: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
7a40: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
7a50: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
7a60: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
7a70: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
7a80: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
7a90: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
7aa0: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
7ab0: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
7ac0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7ad0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
7ae0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
7af0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
7b00: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
7b10: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
7b20: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
7b30: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
7b40: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7b50: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
7b60: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
7b70: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
7b80: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
7b90: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
7ba0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
7bb0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
7bc0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
7bd0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
7be0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
7bf0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
7c00: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
7c10: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
7c20: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
7c30: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
7c40: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
7c50: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
7c60: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
7c70: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
7c80: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
7c90: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
7ca0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
7cb0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
7cc0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
7cd0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
7ce0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
7cf0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
7d00: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
7d10: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
7d20: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
7d30: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
7d40: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
7d50: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
7d60: 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63  se..** A [file c
7d70: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c  ontrol opcodes |
7d80: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7d90: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7da0: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7db0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7dc0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7dd0: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7de0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7df0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7e00: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7e10: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7e20: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7e30: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7e40: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7e50: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7e60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7e70: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7e80: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7e90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7ea0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7eb0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7ec0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7ed0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7ee0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7ef0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7f00: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7f10: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7f20: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7f30: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7f40: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7f50: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7f60: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7f70: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7f80: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7f90: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7fa0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7fb0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7fc0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7fd0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7fe0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7ff0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
8000: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8010: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
8040: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8050: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
8060: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8070: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
8080: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8090: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
80a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80b0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
80c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
80d0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
80e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80f0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
8100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8110: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
8120: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8130: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8140: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8150: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8160: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8170: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8180: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8190: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
81a0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
81b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
81c0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
81d0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
81e0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
81f0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
8200: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
8210: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
8220: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
8230: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8240: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8250: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8260: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8270: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8280: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8290: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
82a0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
82b0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
82c0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
82d0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
82e0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
82f0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8300: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8310: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8320: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
8330: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8340: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8350: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8360: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8370: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8380: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8390: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
83a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
83b0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
83c0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
83d0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
83e0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
83f0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
8400: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
8410: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
8420: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
8430: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8440: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8450: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8460: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8470: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8480: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8490: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
84a0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
84b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
84c0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
84d0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
84e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84f0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8500: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
8510: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
8520: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
8530: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8540: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8550: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8560: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8570: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8580: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8590: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
85a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
85b0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
85c0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
85d0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
85e0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
85f0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
8600: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
8610: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
8620: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
8630: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8640: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8650: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8660: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8670: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8680: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8690: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
86a0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
86b0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
86c0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
86e0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
86f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8700: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8710: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8720: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8730: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8740: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8750: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8760: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8770: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8780: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8790: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
87a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
87b0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
87c0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
87d0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
87e0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
87f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8800: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8810: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8820: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8840: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8850: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8860: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8870: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8880: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8890: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
88a0: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
88d0: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
88e0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
88f0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
8900: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8910: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8920: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
8930: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8940: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8950: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8960: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8970: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8980: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8990: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
89a0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
89b0: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
89c0: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
89d0: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
89e0: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
89f0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
8a00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8a10: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8a20: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8a30: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8a40: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8a50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8a60: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8a70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8a80: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8a90: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8aa0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8ab0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8ac0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8ad0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8ae0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8af0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8b00: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8b10: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8b20: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8b30: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8b40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8b50: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8b60: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8b70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8b80: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8b90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8ba0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8bb0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8bc0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8bd0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8be0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8bf0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8c00: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8c10: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
8c20: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
8c30: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
8c40: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
8c50: 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a  fined..** <ul>.*
8c60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8c70: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8c80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8c90: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8ca0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8cb0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8cc0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8cd0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8ce0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8cf0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8d00: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8d10: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8d20: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8d30: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8d40: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8d50: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8d60: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8d70: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8d80: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8d90: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8da0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8db0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8dc0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8dd0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8de0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8df0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8e00: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8e10: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8e20: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8e30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8e40: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8e50: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8e60: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8e70: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8e80: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8e90: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8ea0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8eb0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8ec0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8ed0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8ee0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
8ef0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
8f00: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
8f10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
8f20: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
8f30: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
8f40: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8f50: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8f60: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
8f70: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8f80: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8f90: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8fa0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8fb0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8fc0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8fd0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8fe0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8ff0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9000: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9010: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9020: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9030: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9040: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
9050: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9060: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9070: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9080: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9090: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
90a0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
90b0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
90c0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
90d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
90e0: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
90f0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9100: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
9110: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
9120: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9130: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9140: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9150: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9170: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9180: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9190: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
91a0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
91b0: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
91c0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
91d0: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
91e0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
91f0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9200: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9210: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
9220: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
9230: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9240: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9250: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9260: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9270: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9280: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9290: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
92a0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
92b0: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
92c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
92d0: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
92e0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
92f0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9300: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
9310: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9320: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
9330: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9340: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
9350: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
9360: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9370: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9380: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9390: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
93a0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
93b0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
93c0: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
93d0: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
93e0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
93f0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9400: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
9410: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9420: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9430: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9440: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9460: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9470: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9480: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9490: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
94a0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
94b0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
94c0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
94d0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
94e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
94f0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9500: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9510: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9520: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
9530: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9540: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
9550: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
9560: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9570: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9580: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9590: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
95a0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
95b0: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
95c0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
95d0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
95e0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
95f0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9600: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
9610: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
9620: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
9630: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9640: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9650: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9660: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9670: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9680: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9690: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
96a0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
96b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
96c0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
96d0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
96e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
96f0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9700: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9710: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9720: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9730: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9740: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9750: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9760: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9770: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9780: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9790: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
97a0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
97b0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
97c0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
97d0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
97e0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
97f0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9800: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9810: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9820: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9830: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9840: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9850: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9860: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9870: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9880: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9890: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
98a0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
98b0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
98c0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
98d0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
98e0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
98f0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9900: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9910: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9920: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9930: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9940: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9950: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9960: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9970: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9980: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9990: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
99a0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
99b0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
99c0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
99d0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
99e0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
99f0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9a00: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9a10: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9a20: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9a30: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9a40: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9a50: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9a60: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9a70: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9a80: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9a90: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9aa0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9ab0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9ac0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9ad0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9ae0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9af0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9b00: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9b10: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9b20: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9b30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9b40: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9b50: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9b60: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9b70: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9b80: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9b90: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9ba0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9bb0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9bc0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9bd0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9be0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9bf0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9c00: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9c10: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9c20: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9c30: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9c40: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9c50: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9c60: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9c70: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9c80: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9c90: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9ca0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9cb0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9cc0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9cd0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9ce0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9cf0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9d00: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9d10: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9d20: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9d30: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9d40: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9d50: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9d60: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9d70: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9d80: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9d90: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9da0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9db0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9dc0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9dd0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9de0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9df0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9e00: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9e10: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9e20: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9e30: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9e40: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9e50: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9e60: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9e70: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9e80: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9e90: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9ea0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9eb0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9ec0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ed0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9ee0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9ef0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9f00: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9f10: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9f20: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9f30: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9f40: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9f50: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9f60: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9f70: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
9f80: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
9f90: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
9fa0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
9fb0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
9fc0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
9fd0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9fe0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9ff0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a000: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a010: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a020: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a030: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a040: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a050: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a060: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a070: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a080: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a090: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a0a0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a0b0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a0c0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a0d0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a0e0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a0f0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a100: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a110: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a120: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a130: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a140: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a150: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a160: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a170: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a180: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a190: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a1a0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a1b0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a1c0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a1d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a1e0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a1f0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a200: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a210: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a220: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a230: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a240: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a250: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a260: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a270: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a280: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a290: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a2a0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a2b0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a2c0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a2d0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a2e0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a2f0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a300: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a310: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a320: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a330: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a340: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a350: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a360: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a370: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a380: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a390: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a3a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a3b0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a3c0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a3d0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a3e0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a3f0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a400: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a410: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a420: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a430: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a440: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a450: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a460: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a470: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a480: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a490: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a4a0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a4b0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a4c0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a4d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a4e0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a4f0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a500: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a510: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a520: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a530: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a540: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a550: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a560: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a570: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a580: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a590: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a5a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a5b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a5c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a5d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a5e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a5f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a600: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a610: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a620: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a630: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a640: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a650: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a660: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a670: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a680: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a690: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a6a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a6b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a6c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a6d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a6e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a6f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a700: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a710: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a720: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a730: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a740: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a750: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a760: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a770: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a780: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a790: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a7a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a7b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a7c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a7d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a7e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a7f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a800: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a810: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a820: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a830: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a840: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a850: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a860: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a870: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a880: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a890: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a8a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a8b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a8c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a8d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a8e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a8f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a900: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a910: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a920: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a930: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a940: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a950: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a960: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a970: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a980: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a990: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a9a0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a9b0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a9c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a9d0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a9e0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a9f0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
aa00: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
aa10: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
aa20: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
aa30: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
aa40: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
aa50: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
aa60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa70: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
aa80: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
aa90: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
aaa0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
aab0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
aac0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
aad0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
aae0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
aaf0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
ab00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ab10: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
ab20: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
ab30: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
ab40: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
ab50: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
ab60: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
ab70: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
ab80: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
ab90: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
aba0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
abb0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
abc0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
abd0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
abe0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
abf0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
ac00: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
ac10: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
ac20: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
ac30: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
ac40: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
ac50: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
ac60: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
ac70: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
ac80: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
ac90: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
aca0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
acb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
acc0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
acd0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
ace0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
acf0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
ad00: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
ad10: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
ad20: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
ad30: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
ad40: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
ad50: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
ad60: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
ad70: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
ad80: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
ad90: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
ada0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
adb0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
adc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
add0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
ade0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
adf0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ae00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ae10: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ae20: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
ae30: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
ae40: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
ae50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
ae60: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
ae70: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
ae80: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ae90: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
aea0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
aeb0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
aec0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
aed0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
aee0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
aef0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
af00: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
af10: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
af20: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
af30: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
af40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
af50: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
af60: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
af70: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
af80: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
af90: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
afa0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
afb0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
afc0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
afd0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
afe0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
aff0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b000: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
b010: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
b020: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b030: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
b040: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
b050: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
b060: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b070: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
b080: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
b090: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
b0a0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
b0b0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
b0c0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
b0d0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
b0e0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
b0f0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
b100: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
b110: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
b120: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
b130: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
b140: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
b150: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
b160: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
b170: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
b180: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
b190: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
b1a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
b1b0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
b1c0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
b1d0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
b1e0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
b1f0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
b200: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
b210: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b220: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
b230: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b240: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
b250: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
b260: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
b270: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
b280: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b290: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b2a0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b2b0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b2c0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b2d0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b2e0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b2f0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b300: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b310: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
b320: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
b330: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
b340: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
b350: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
b360: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
b370: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
b380: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
b390: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
b3a0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b3b0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
b3c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b3d0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b3e0: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
b3f0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b400: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
b410: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
b420: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
b430: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
b440: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
b450: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
b460: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
b470: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
b480: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
b490: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
b4a0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
b4b0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
b4c0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
b4d0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
b4e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b4f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
b500: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
b510: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b520: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
b530: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
b540: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
b550: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
b560: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
b570: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
b580: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
b590: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
b5a0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
b5b0: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
b5c0: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
b5d0: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
b5e0: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
b5f0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
b600: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
b610: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
b620: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
b630: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b640: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a  CNTL_ZIPVFS]].**
b650: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b660: 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64  TL_ZIPVFS] opcod
b670: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
b680: 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e   by zipvfs only.
b690: 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46   All other.** VF
b6a0: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
b6b0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
b6c0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  for this opcode.
b6d0: 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .**.** </ul>.*/.
b6e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b6f0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
b700: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
b710: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b720: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
b730: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
b740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b750: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
b760: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
b770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b780: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
b790: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
b7a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b7b0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
b7c0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
b7d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b7e0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
b7f0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
b800: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
b810: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
b820: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
b830: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
b840: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
b850: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
b860: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b870: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
b880: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
b890: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
b8a0: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
b8b0: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
b8c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
b8d0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
b8e0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
b8f0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
b900: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
b910: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
b920: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
b930: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
b940: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
b950: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
b960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b970: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
b980: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b990: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
b9a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9b0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
b9c0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
b9d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b9e0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
b9f0: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
ba00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ba10: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
ba20: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
ba30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ba40: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
ba50: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
ba60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ba70: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
ba80: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
ba90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
baa0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
bab0: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
bac0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bad0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bae0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
baf0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a  e SQLITE_FCNTL_Z
bb00: 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20  IPVFS           
bb10: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65        24.#define
bb20: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 54   SQLITE_FCNTL_OT
bb30: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
bb40: 20 20 20 20 20 32 35 0a 0a 2f 2a 20 64 65 70 72       25../* depr
bb50: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
bb60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
bb70: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
bb80: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
bb90: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
bba0: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
bbb0: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
bbc0: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
bbd0: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
bbe0: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
bbf0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
bc00: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
bc10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
bc20: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
bc30: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
bc40: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
bc50: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
bc60: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
bc70: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
bc80: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
bc90: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
bca0: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
bcb0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
bcc0: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
bcd0: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
bce0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
bcf0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
bd00: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
bd10: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
bd20: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
bd30: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
bd40: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
bd50: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
bd60: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
bd70: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
bd80: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
bd90: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
bda0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
bdb0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
bdc0: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
bdd0: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
bde0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
bdf0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
be00: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
be10: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
be20: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
be30: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
be40: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
be50: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
be60: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
be70: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
be80: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
be90: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
bea0: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
beb0: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
bec0: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
bed0: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
bee0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
bef0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
bf00: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
bf10: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
bf20: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
bf30: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
bf40: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
bf50: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
bf60: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
bf70: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
bf80: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
bf90: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
bfa0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
bfb0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
bfc0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
bfd0: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
bfe0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
bff0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
c000: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
c010: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
c020: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
c030: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
c040: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
c050: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
c060: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
c070: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
c080: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
c090: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
c0a0: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
c0b0: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
c0c0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
c0d0: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
c0e0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
c0f0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
c100: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
c110: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
c120: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
c130: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
c140: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
c150: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
c160: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
c170: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
c180: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
c190: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
c1a0: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
c1b0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
c1c0: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
c1d0: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
c1e0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
c1f0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
c200: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
c210: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
c220: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
c230: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
c240: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
c250: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
c260: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
c270: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
c280: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
c290: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
c2a0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
c2b0: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
c2c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
c2d0: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
c2e0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
c2f0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
c300: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
c310: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
c320: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
c330: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
c340: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
c350: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c360: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
c370: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
c380: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
c390: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
c3a0: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
c3b0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
c3c0: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
c3d0: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
c3e0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
c3f0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
c400: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
c410: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
c420: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
c430: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
c440: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
c450: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
c460: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
c470: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
c480: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
c490: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
c4a0: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
c4b0: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
c4c0: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
c4d0: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
c4e0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
c4f0: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
c500: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
c510: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
c520: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
c530: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
c540: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
c550: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
c560: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
c570: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
c580: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
c590: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
c5a0: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
c5b0: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
c5c0: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
c5d0: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
c5e0: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
c5f0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
c600: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
c610: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
c620: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
c630: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
c640: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
c650: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
c660: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
c670: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c680: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
c690: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
c6a0: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
c6b0: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
c6c0: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
c6d0: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
c6e0: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
c6f0: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
c700: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
c710: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
c720: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
c730: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
c740: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
c750: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
c760: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
c770: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
c780: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
c790: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
c7a0: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
c7b0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
c7c0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
c7d0: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
c7e0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
c7f0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c800: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
c810: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
c820: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
c830: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
c840: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
c850: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
c860: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
c870: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
c880: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
c890: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
c8a0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
c8b0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
c8c0: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
c8d0: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
c8e0: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
c8f0: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
c900: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
c910: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
c920: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
c930: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
c940: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
c950: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
c960: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
c970: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c980: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
c990: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c9a0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
c9b0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c9c0: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
c9d0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c9e0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
c9f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ca00: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
ca10: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
ca20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
ca30: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
ca40: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
ca50: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
ca60: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ca70: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
ca80: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
ca90: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
caa0: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
cab0: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
cac0: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
cad0: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
cae0: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
caf0: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
cb00: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
cb10: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
cb20: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
cb30: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
cb40: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
cb50: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
cb60: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
cb70: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
cb80: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
cb90: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
cba0: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
cbb0: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
cbc0: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
cbd0: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
cbe0: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
cbf0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
cc00: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
cc10: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
cc20: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
cc30: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
cc40: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
cc50: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
cc60: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
cc70: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
cc80: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
cc90: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
cca0: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
ccb0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
ccc0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
ccd0: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
cce0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
ccf0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
cd00: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cd10: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
cd20: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
cd30: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
cd40: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
cd50: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
cd60: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
cd70: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
cd80: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
cd90: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
cda0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
cdb0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
cdc0: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
cdd0: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
cde0: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
cdf0: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
ce00: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
ce10: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
ce20: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
ce30: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
ce40: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
ce50: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
ce60: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
ce70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
ce80: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
ce90: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
cea0: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
ceb0: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
cec0: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
ced0: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
cee0: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
cef0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
cf00: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
cf10: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
cf20: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
cf30: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
cf40: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
cf50: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
cf60: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
cf70: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
cf80: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
cf90: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
cfa0: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
cfb0: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
cfc0: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
cfd0: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
cfe0: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
cff0: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
d000: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
d010: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
d020: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
d030: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
d040: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
d050: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
d060: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
d070: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
d080: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
d090: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
d0a0: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
d0b0: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
d0c0: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
d0d0: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
d0e0: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
d0f0: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
d100: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
d110: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
d120: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
d130: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
d140: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
d150: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
d160: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
d170: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
d180: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
d190: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
d1a0: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
d1b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
d1c0: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
d1d0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
d1e0: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
d1f0: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
d200: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
d210: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
d220: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
d230: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
d240: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
d250: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
d260: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
d270: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
d280: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
d290: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
d2a0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
d2b0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
d2c0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
d2d0: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
d2e0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
d2f0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
d300: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
d310: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
d320: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
d330: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
d340: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
d350: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
d360: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
d370: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
d380: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
d390: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
d3a0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
d3b0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
d3c0: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
d3d0: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
d3e0: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
d3f0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
d400: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
d410: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
d420: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
d430: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
d440: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
d450: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
d460: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
d470: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
d480: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
d490: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
d4a0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
d4b0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
d4c0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
d4d0: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
d4e0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
d4f0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
d500: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
d510: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
d520: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
d530: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
d540: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
d550: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
d560: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
d570: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
d580: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
d590: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
d5a0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
d5b0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
d5c0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
d5d0: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
d5e0: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
d5f0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
d600: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
d610: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
d620: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
d630: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
d640: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
d650: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
d660: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
d670: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
d680: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
d690: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
d6a0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
d6b0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
d6c0: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
d6d0: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
d6e0: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
d6f0: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
d700: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
d710: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
d720: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
d730: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
d740: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
d750: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
d760: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
d770: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
d780: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
d790: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
d7a0: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
d7b0: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
d7c0: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
d7d0: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
d7e0: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
d7f0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
d800: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
d810: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
d820: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
d830: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
d840: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
d850: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
d860: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
d870: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
d880: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
d890: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
d8a0: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
d8b0: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
d8c0: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
d8d0: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
d8e0: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
d8f0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
d900: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
d910: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
d920: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
d930: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
d940: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
d950: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
d960: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
d970: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
d980: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
d990: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
d9a0: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
d9b0: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
d9c0: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
d9d0: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
d9e0: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
d9f0: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
da00: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
da10: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
da20: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
da30: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
da40: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
da50: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
da60: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
da70: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
da80: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
da90: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
daa0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
dab0: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
dac0: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
dad0: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
dae0: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
daf0: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
db00: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
db10: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
db20: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
db30: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
db40: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
db50: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
db60: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
db70: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
db80: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
db90: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
dba0: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
dbb0: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
dbc0: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
dbd0: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
dbe0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
dbf0: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
dc00: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
dc10: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
dc20: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
dc30: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
dc40: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
dc50: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
dc60: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
dc70: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
dc80: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
dc90: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
dca0: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
dcb0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
dcc0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
dcd0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
dce0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
dcf0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
dd00: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
dd10: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
dd20: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
dd30: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
dd40: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
dd50: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
dd60: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
dd70: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
dd80: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
dd90: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
dda0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
ddb0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
ddc0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
ddd0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
dde0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
ddf0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
de00: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
de10: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
de20: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
de30: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
de40: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
de50: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
de60: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
de70: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
de80: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
de90: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
dea0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
deb0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
dec0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ded0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
dee0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
def0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
df00: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
df10: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
df20: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
df30: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
df40: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
df50: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
df60: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
df70: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
df80: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
df90: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
dfa0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
dfb0: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
dfc0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
dfd0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
dfe0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
dff0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
e000: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
e010: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
e020: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e030: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
e040: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
e050: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e060: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
e070: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
e080: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
e090: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
e0a0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
e0b0: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
e0c0: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
e0d0: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
e0e0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
e0f0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
e100: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
e110: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
e120: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
e130: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
e140: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e150: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e160: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
e170: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
e180: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
e190: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
e1a0: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
e1b0: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
e1c0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
e1d0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
e1e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
e1f0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
e200: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e210: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e220: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
e230: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
e240: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
e250: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
e260: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
e270: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
e280: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
e290: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e2a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e2b0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
e2c0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
e2d0: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
e2e0: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
e2f0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e300: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e310: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
e320: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
e330: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
e340: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e350: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
e360: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e370: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e380: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
e390: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
e3a0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
e3b0: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
e3c0: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
e3d0: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
e3e0: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
e3f0: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
e400: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
e410: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
e420: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
e430: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
e440: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
e450: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
e460: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
e470: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
e480: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
e490: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
e4a0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
e4b0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
e4c0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
e4d0: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
e4e0: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
e4f0: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
e500: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e510: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
e520: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
e530: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
e540: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e550: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
e560: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e570: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
e580: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
e590: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
e5a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e5b0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
e5c0: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
e5d0: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
e5e0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
e5f0: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
e600: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
e610: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
e620: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
e630: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
e640: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
e650: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
e660: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
e670: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
e680: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
e690: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
e6a0: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
e6b0: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
e6c0: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
e6d0: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
e6e0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
e6f0: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
e700: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
e710: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e720: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
e730: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
e740: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
e750: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e760: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
e770: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
e780: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
e790: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
e7a0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
e7b0: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
e7c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e7d0: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
e7e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
e7f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
e800: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
e810: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
e820: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
e830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e840: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
e850: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
e860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e870: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
e880: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
e890: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
e8a0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
e8b0: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
e8c0: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
e8d0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
e8e0: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
e8f0: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
e900: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
e910: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
e920: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
e930: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
e940: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
e950: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
e960: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
e970: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
e980: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
e990: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
e9a0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
e9b0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
e9c0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
e9d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
e9e0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
e9f0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
ea00: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
ea10: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
ea20: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
ea30: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
ea40: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
ea50: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
ea60: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
ea70: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
ea80: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
ea90: 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
eaa0: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
eab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
eac0: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
ead0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
eae0: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
eaf0: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
eb00: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
eb10: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
eb20: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
eb30: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
eb40: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
eb50: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
eb60: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
eb70: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
eb80: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
eb90: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
eba0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
ebb0: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
ebc0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
ebd0: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
ebe0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
ebf0: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
ec00: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
ec10: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
ec20: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
ec30: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
ec40: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
ec50: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
ec60: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
ec70: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
ec80: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
ec90: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
eca0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
ecb0: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
ecc0: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
ecd0: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
ece0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ecf0: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
ed00: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
ed10: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
ed20: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
ed30: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
ed40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ed50: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
ed60: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
ed70: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
ed80: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
ed90: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
eda0: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
edb0: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
edc0: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
edd0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
ede0: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
edf0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
ee00: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
ee10: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
ee20: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
ee30: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
ee40: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
ee50: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
ee60: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
ee70: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
ee80: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
ee90: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
eea0: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
eeb0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
eec0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
eed0: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
eee0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
eef0: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
ef00: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
ef10: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ef20: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
ef30: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
ef40: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
ef50: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
ef60: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
ef70: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ef80: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
ef90: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
efa0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
efb0: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
efc0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
efd0: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
efe0: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
eff0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
f000: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
f010: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
f020: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
f030: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
f040: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f050: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
f060: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
f070: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
f080: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f090: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
f0a0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
f0b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
f0c0: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
f0d0: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
f0e0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f0f0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
f100: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
f110: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
f120: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
f130: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
f140: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
f150: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
f160: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f170: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
f180: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
f190: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f1a0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
f1b0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
f1c0: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
f1d0: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
f1e0: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
f1f0: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
f200: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
f210: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
f220: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
f230: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
f240: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
f250: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
f260: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
f270: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
f280: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
f290: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
f2a0: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
f2b0: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
f2c0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
f2d0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
f2e0: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
f2f0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
f300: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
f310: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
f320: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
f330: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
f340: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
f350: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
f360: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
f370: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
f380: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f390: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
f3a0: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
f3b0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
f3c0: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
f3d0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
f3e0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
f3f0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
f400: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
f410: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
f420: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
f430: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
f440: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f450: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
f460: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
f470: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
f480: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
f490: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
f4a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
f4b0: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
f4c0: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
f4d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f4e0: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
f4f0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
f500: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
f510: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
f520: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
f530: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
f540: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
f550: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
f560: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
f570: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
f580: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
f590: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
f5a0: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
f5b0: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
f5c0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f5d0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
f5e0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
f5f0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
f600: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
f610: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
f620: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
f630: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
f640: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
f650: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
f660: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
f670: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
f680: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
f690: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
f6a0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f6b0: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
f6c0: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
f6d0: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
f6e0: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
f6f0: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
f700: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f710: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
f720: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
f730: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
f740: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
f750: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
f760: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
f770: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
f780: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
f790: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
f7a0: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
f7b0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f7c0: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
f7d0: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
f7e0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
f7f0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
f800: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
f810: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
f820: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
f830: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
f840: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
f850: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
f860: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
f870: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
f880: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
f890: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
f8a0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
f8b0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
f8c0: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
f8d0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
f8e0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
f8f0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
f900: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
f910: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
f920: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
f930: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
f940: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f950: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
f960: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
f970: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
f980: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
f990: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
f9a0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
f9b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
f9c0: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
f9d0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
f9e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
f9f0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
fa00: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
fa10: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
fa20: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
fa30: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
fa40: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
fa50: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
fa60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fa70: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
fa80: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
fa90: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
faa0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
fab0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
fac0: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
fad0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fae0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
faf0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
fb00: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
fb10: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
fb20: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
fb30: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
fb40: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fb50: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
fb60: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
fb70: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
fb80: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
fb90: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
fba0: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
fbb0: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
fbc0: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
fbd0: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
fbe0: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
fbf0: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
fc00: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
fc10: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
fc20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
fc30: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
fc40: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
fc50: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
fc60: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
fc70: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
fc80: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
fc90: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
fca0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
fcb0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fcc0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
fcd0: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
fce0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
fcf0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
fd00: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
fd10: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
fd20: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
fd30: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fd40: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
fd50: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
fd60: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
fd70: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
fd80: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
fd90: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
fda0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
fdb0: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
fdc0: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
fdd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
fde0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
fdf0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
fe00: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
fe10: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
fe20: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
fe30: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
fe40: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
fe50: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
fe60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
fe70: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
fe80: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
fe90: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
fea0: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
feb0: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
fec0: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
fed0: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
fee0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
fef0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
ff00: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
ff10: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
ff20: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
ff30: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
ff40: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
ff50: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
ff60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ff70: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
ff80: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
ff90: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
ffa0: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
ffb0: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
ffc0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
ffd0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
ffe0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
fff0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
10000 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
10010 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
10020 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
10030 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
10040 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10050 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
10060 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
10070 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
10080 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
10090 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
100a0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
100b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
100c0 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
100d0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
100e0 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
100f0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
10100 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
10110 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
10120 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
10130 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
10140 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
10150 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
10160 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
10170 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
10180 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
10190 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
101a0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
101b0 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
101c0 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
101d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
101e0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
101f0 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
10200 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
10210 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
10220 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
10230 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
10240 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
10250 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
10260 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
10270 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
10280 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
10290 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
102a0 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
102b0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
102c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
102d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
102e0 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
102f0 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
10300 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
10310 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
10320 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
10330 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
10340 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
10350 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
10360 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
10370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10380 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
10390 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  connections.**.*
103a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
103b0 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
103c0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
103d0 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
103e0 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
103f0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
10400 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
10410 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
10420 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
10430 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
10440 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
10450 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
10460 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
10470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
10480 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
10490 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
104a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
104b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
104c0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
104d0 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
104e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
104f0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10500 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
10510 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
10520 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
10530 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
10540 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
10550 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10560 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
10570 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
10580 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
10590 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
105a0 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
105b0 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
105c0 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
105d0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
105e0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
105f0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
10600 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
10610 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
10620 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
10630 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
10640 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
10650 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
10660 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
10670 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
10680 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
10690 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
106a0 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
106b0 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
106c0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
106d0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
106e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
106f0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
10700 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
10710 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
10720 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
10730 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
10740 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
10750 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
10760 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
10770 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
10780 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
10790 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
107a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
107b0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
107c0 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
107d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
107e0 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
107f0 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
10800 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
10810 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
10820 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
10830 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
10840 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
10850 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
10860 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
10870 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
10880 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
10890 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
108a0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
108b0 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
108c0 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
108d0 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
108e0 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
108f0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
10900 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
10910 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
10920 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
10930 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
10940 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
10950 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
10960 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
10970 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
10980 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
10990 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
109a0 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
109b0 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
109c0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
109d0 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
109e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
109f0 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
10a00 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
10a10 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
10a20 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
10a30 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
10a40 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
10a50 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
10a60 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
10a70 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
10a80 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
10a90 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
10aa0 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
10ab0 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
10ac0 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
10ad0 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
10ae0 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
10af0 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
10b00 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
10b10 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
10b20 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
10b30 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
10b40 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
10b50 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
10b60 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
10b70 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
10b80 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
10b90 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
10ba0 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
10bb0 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
10bc0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
10bd0 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
10be0 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
10bf0 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
10c00 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
10c10 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
10c20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
10c30 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
10c40 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
10c50 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
10c60 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
10c70 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
10c80 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
10c90 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
10ca0 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
10cb0 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
10cc0 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
10cd0 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
10ce0 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
10cf0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
10d00 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
10d10 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
10d20 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
10d30 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
10d40 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
10d50 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
10d60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
10d70 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
10d80 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
10d90 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
10da0 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
10db0 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
10dc0 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
10dd0 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
10de0 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
10df0 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
10e00 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
10e10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
10e20 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
10e30 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
10e40 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
10e50 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
10e60 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
10e70 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
10e80 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
10e90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
10ea0 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
10eb0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
10ec0 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
10ed0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
10ee0 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a    For example,.*
10ef0 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
10f00 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
10f10 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
10f20 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
10f30 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
10f40 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
10f50 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
10f60 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
10f70 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
10f80 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
10f90 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
10fa0 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
10fb0 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
10fc0 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
10fd0 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
10fe0 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
10ff0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
11000 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
11010 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
11020 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
11030 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
11040 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
11050 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
11060 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
11070 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
11080 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
11090 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
110a0 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
110b0 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
110c0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
110d0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
110e0 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
110f0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
11100 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
11110 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
11120 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
11130 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
11140 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
11150 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
11160 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
11170 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11180 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
11190 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
111a0 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
111b0 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
111c0 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
111d0 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
111e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
111f0 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
11200 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
11210 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11220 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
11230 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
11240 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
11250 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
11260 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
11270 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
11280 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
11290 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
112a0 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
112b0 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
112c0 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
112d0 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
112e0 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
112f0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
11300 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
11310 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11320 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11330 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
11340 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11350 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
11360 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
11370 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
11380 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
11390 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
113a0 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
113b0 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
113c0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
113d0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
113e0 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
113f0 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
11400 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
11410 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
11420 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
11430 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
11440 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
11450 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
11460 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
11470 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
11480 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
11490 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
114a0 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
114b0 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
114c0 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
114d0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
114e0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
114f0 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
11500 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
11510 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
11520 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
11530 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
11540 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
11550 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
11560 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
11570 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
11580 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
11590 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
115a0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20  tion Options.** 
115b0 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69  KEYWORDS: {confi
115c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d  guration option}
115d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
115e0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
115f0 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
11600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11610 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
11620 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
11630 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11640 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
11650 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
11660 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
11670 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
11680 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
11690 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
116a0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
116b0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
116c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
116d0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
116e0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
116f0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
11700 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
11710 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
11720 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11730 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
11740 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
11750 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
11760 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11770 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
11780 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
11790 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
117a0 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
117b0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
117c0 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
117d0 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
117e0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
117f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11800 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
11810 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11820 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11830 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11840 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11850 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11860 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11870 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11880 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11890 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
118a0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
118b0 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
118c0 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
118d0 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
118e0 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
118f0 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
11900 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
11910 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
11920 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11930 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
11940 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
11950 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
11960 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
11970 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
11980 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
11990 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
119a0 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
119b0 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
119c0 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
119d0 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
119e0 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
119f0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
11a00 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
11a10 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
11a20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
11a30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11a40 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
11a50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11a60 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
11a70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11a80 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74  ULTITHREAD]] <dt
11a90 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
11aa0 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
11ab0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11ac0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11ad0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11ae0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11af0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11b00 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
11b10 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
11b20 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
11b30 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
11b40 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
11b50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
11b60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11b70 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
11b80 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
11b90 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
11ba0 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
11bb0 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
11bc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11bd0 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
11be0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
11bf0 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
11c00 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
11c10 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
11c20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
11c30 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
11c40 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
11c50 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
11c60 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
11c70 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
11c80 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
11c90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11ca0 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
11cb0 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
11cc0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11cd0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11ce0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11cf0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11d00 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11d10 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11d20 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11d30 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
11d40 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
11d50 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
11d60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11d70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
11d80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
11d90 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
11da0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
11db0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
11dc0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11dd0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11de0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11df0 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74  SERIALIZED]] <dt
11e00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
11e10 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
11e20 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
11e30 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
11e40 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
11e50 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
11e60 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
11e70 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
11e80 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
11e90 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
11ea0 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
11eb0 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
11ec0 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
11ed0 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
11ee0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11ef0 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
11f00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
11f10 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
11f20 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
11f30 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
11f40 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
11f50 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
11f60 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11f70 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
11f80 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
11f90 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
11fa0 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
11fb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
11fc0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11fd0 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
11fe0 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
11ff0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
12000 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
12010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12020 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
12030 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
12040 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
12050 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
12060 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
12070 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
12080 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12090 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
120a0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
120b0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
120c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
120d0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
120e0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
120f0 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
12100 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
12110 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
12120 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12130 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
12140 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
12150 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
12160 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12170 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
12180 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12190 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
121a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
121b0 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
121c0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
121d0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
121e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
121f0 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
12200 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12210 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
12220 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12230 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12240 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12250 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12260 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
12270 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
12280 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
12290 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
122a0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
122b0 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
122c0 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
122d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
122e0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
122f0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
12300 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
12310 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
12320 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
12330 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
12340 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12350 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
12360 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
12370 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
12380 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
12390 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
123a0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
123b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
123c0 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
123d0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
123e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
123f0 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
12400 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12410 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
12420 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12430 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12440 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12450 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12460 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  e..** The [sqlit
12470 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
12480 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
12490 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
124a0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
124b0 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
124c0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
124d0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
124e0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
124f0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
12500 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
12510 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
12520 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
12530 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
12540 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12550 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
12560 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
12570 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
12580 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
12590 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
125a0 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53  EMSTATUS]] <dt>S
125b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
125c0 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
125d0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
125e0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
125f0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
12600 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
12610 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e   type int,.** in
12620 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
12630 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
12640 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
12650 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
12660 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c   of.** memory al
12670 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12680 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
12690 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
126a0 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20  atistics are.** 
126b0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f  disabled, the fo
126c0 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
126d0 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
126e0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
126f0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
12700 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
12710 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
12720 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12730 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
12740 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
12750 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
12760 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
12770 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
12780 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
12790 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
127a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
127b0 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
127c0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
127d0 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
127e0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
127f0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
12800 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
12810 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
12820 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
12830 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
12840 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
12850 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
12860 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12870 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
12880 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12890 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
128a0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
128b0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
128c0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
128d0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
128e0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
128f0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
12900 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  or scratch memor
12910 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20  y.  ^(There are 
12920 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a  three arguments.
12930 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ** to SQLITE_CON
12940 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20  FIG_SCRATCH:  A 
12950 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
12960 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
12970 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
12980 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
12990 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
129a0 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
129b0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
129c0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
129d0 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
129e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
129f0 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
12a00 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29  llocations (N).)
12a10 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ^.** The first a
12a20 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
12a30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
12a40 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
12a50 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
12a60 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
12a70 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
12a80 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75  QLite will not u
12a90 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  se more than one
12aa0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
12ab0 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20   per thread..** 
12ac0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
12ad0 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72  er request a scr
12ae0 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
12af0 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
12b00 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
12b10 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
12b20 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  .** ^If SQLite n
12b30 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
12b40 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
12b50 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
12b60 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
12b70 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
12b80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
12b90 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
12ba0 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
12bb0 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
12bc0 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
12bd0 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20  ed.<p>.** ^When 
12be0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
12bf0 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f  provides any amo
12c00 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d  unt of scratch m
12c10 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53  emory using.** S
12c20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12c30 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f  ATCH, SQLite avo
12c40 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20  ids unnecessary 
12c50 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  large.** [sqlite
12c60 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c  3_malloc|heap al
12c70 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  locations]..** T
12c80 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f  his can help [Ro
12c90 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65  bson proof|preve
12ca0 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  nt memory alloca
12cb0 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64  tion failures] d
12cc0 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72  ue to heap.** fr
12cd0 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c  agmentation in l
12ce0 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64  ow-memory embedd
12cf0 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c  ed systems..** <
12d00 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12d10 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
12d20 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
12d30 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
12d40 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
12d50 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
12d60 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
12d70 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
12d80 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
12d90 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ffer.** that SQL
12da0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
12db0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
12dc0 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
12dd0 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a   default page.**
12de0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
12df0 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
12e00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73   configuration s
12e10 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
12e20 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  d if an applicat
12e30 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
12e40 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
12e50 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
12e60 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  d using the [SQL
12e70 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
12e80 45 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  E2].** configura
12e90 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  tion option..** 
12ea0 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
12eb0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
12ec0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
12ed0 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72  CACHE: A pointer
12ee0 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c   to.** 8-byte al
12ef0 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  igned.** memory,
12f00 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
12f10 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
12f20 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
12f30 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
12f40 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
12f50 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
12f60 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
12f70 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
12f80 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
12f90 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
12fa0 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
12fb0 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
12fc0 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
12fd0 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
12fe0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
12ff0 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
13000 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
13010 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
13020 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ermined using th
13030 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
13040 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f  _PCACHE_HDRSZ] o
13050 70 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71  ption .** to [sq
13060 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
13070 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  .** ^It is harml
13080 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
13090 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
130a0 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a  y,.** for the sz
130b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
130c0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63   larger than nec
130d0 65 73 73 61 72 79 2e 20 20 54 68 65 20 66 69 72  essary.  The fir
130e0 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
130f0 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f  hould pointer to
13100 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
13110 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f  ed block of memo
13120 72 79 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 74  ry that.** is at
13130 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
13140 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68  s of memory, oth
13150 65 72 77 69 73 65 20 73 75 62 73 65 71 75 65 6e  erwise subsequen
13160 74 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  t behavior is.**
13170 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
13180 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
13190 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
131a0 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
131b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
131c0 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
131d0 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
131e0 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
131f0 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
13200 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
13210 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
13220 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
13230 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
13240 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
13250 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
13260 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
13270 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13280 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
13290 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
132a0 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a  e space.</dd>.**
132b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
132c0 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
132d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
132e0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
132f0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13300 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
13310 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
13320 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
13330 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
13340 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
13350 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
13360 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13370 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
13380 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
13390 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
133a0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
133b0 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  nd.** [SQLITE_CO
133c0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
133d0 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
133e0 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
133f0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
13400 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
13410 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
13420 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  th either [SQLIT
13430 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
13440 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ] or [SQLITE_ENA
13450 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64  BLE_MEMSYS5] and
13460 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
13470 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e  ITE_ERROR] if in
13480 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e  voked otherwise.
13490 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
134a0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
134b0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
134c0 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79  HEAP:.** An 8-by
134d0 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
134e0 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
134f0 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
13500 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
13510 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
13520 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
13530 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
13540 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
13550 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
13560 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
13570 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
13580 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
13590 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
135a0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
135b0 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
135c0 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
135d0 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
135e0 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
135f0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
13600 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
13610 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
13620 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
13630 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
13640 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
13650 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
13660 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
13670 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
13680 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
13690 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
136a0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
136b0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
136c0 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
136d0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
136e0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
136f0 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
13700 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
13710 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
13720 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
13730 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
13740 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
13750 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
13760 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
13770 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
13780 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13790 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
137a0 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
137b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
137c0 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
137d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
137e0 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
137f0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
13800 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e  FIG_MUTEX option
13810 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13820 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13830 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
13840 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
13850 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
13860 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
13870 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
13880 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
13890 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  s alternative lo
138a0 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
138b0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
138c0 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68  d.** in place th
138d0 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
138e0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
138f0 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
13900 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  akes a copy of.*
13910 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
13920 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
13930 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
13940 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
13950 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
13960 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13970 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
13980 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13990 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
139a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
139b0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
139c0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
139d0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
139e0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
139f0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
13a00 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
13a10 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
13a20 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
13a30 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13a40 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
13a50 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
13a60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13a70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
13a80 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
13a90 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
13aa0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
13ab0 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
13ac0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13ad0 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
13ae0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
13af0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f  ONFIG_GETMUTEX o
13b00 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13b10 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13b20 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
13b30 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
13b40 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
13b50 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
13b60 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
13b70 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
13b80 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
13b90 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
13ba0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
13bb0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
13bc0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
13bd0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
13be0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
13bf0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
13c00 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
13c10 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
13c20 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
13c30 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
13c40 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
13c50 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
13c60 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
13c70 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
13c80 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
13c90 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
13ca0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
13cb0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13cc0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
13cd0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13ce0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
13cf0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
13d00 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
13d10 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
13d20 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
13d30 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
13d40 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
13d50 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
13d60 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
13d70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13d80 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
13d90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
13da0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13db0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
13dc0 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
13dd0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
13de0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
13df0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
13e00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70  FIG_LOOKASIDE op
13e10 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
13e20 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
13e30 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64  termine.** the d
13e40 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c  efault size of l
13e50 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
13e60 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73  on each [databas
13e70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
13e80 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
13e90 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
13ea0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
13eb0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
13ec0 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
13ed0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
13ee0 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
13ef0 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
13f00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13f10 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f  .)^  ^(SQLITE_CO
13f20 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a  NFIG_LOOKASIDE.*
13f30 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65  * sets the <i>de
13f40 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
13f50 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
13f60 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
13f70 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74  OOKASIDE].** opt
13f80 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ion to [sqlite3_
13f90 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
13fa0 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
13fb0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
13fc0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
13fd0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
13fe0 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
13ff0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14000 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
14010 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
14020 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
14030 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
14040 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14050 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
14060 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14070 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
14080 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
14090 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
140a0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
140b0 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
140c0 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ct specifies.** 
140d0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  the interface to
140e0 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
140f0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
14100 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74  ion.)^.** ^SQLit
14110 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
14120 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  f the [sqlite3_p
14130 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
14140 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
14150 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14160 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
14170 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14180 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
14190 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
141a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
141b0 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  TPCACHE2 option 
141c0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
141d0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
141e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
141f0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
14200 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
14210 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
14220 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63  pies of.** the c
14230 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68  urrent page cach
14240 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14250 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
14260 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
14270 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14280 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
14290 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
142a0 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
142b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
142c0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
142d0 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
142e0 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
142f0 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
14300 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
14310 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
14320 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
14330 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
14340 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
14350 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
14360 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
14370 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
14380 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
14390 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
143a0 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
143b0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
143c0 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
143d0 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
143e0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
143f0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
14400 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
14410 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
14420 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
14430 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
14440 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
14450 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
14460 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
14470 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
14480 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14490 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
144a0 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
144b0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
144c0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
144d0 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
144e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
144f0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
14500 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
14510 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
14520 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
14530 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
14540 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
14550 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
14560 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
14570 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
14580 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
14590 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
145a0 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
145b0 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
145c0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
145d0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
145e0 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
145f0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
14600 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
14610 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
14620 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
14630 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
14640 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
14650 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
14660 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
14670 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
14680 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
14690 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
146a0 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
146b0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
146c0 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
146d0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
146e0 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
146f0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
14700 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
14710 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
14720 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
14730 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
14740 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14750 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
14760 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14770 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
14780 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14790 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74  FIG_URI option t
147a0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
147b0 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
147c0 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65  nt..** If non-ze
147d0 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
147e0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
147f0 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
14800 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
14810 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49  ero,.** then URI
14820 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14830 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29  bally disabled.)
14840 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69  ^ ^If URI handli
14850 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
14860 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  * enabled, all f
14870 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20  ilenames passed 
14880 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
14890 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
148a0 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  en_v2()],.** [sq
148b0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
148c0 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
148d0 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
148e0 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
148f0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
14900 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
14910 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
14920 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
14930 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
14940 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
14950 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
14960 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
14970 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
14980 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
14990 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
149a0 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
149b0 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
149c0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
149d0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
149e0 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
149f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
14a00 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
14a10 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
14a20 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
14a30 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
14a40 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
14a50 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
14a60 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
14a70 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
14a80 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
14a90 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
14aa0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
14ab0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
14ac0 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
14ad0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
14ae0 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
14af0 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
14b00 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
14b10 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20  DEX_SCAN option 
14b20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
14b30 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65  nteger.** argume
14b40 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
14b50 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
14b60 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
14b70 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
14b80 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  le.** the use of
14b90 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
14ba0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
14bb0 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
14bc0 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a  ery optimizer..*
14bd0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
14be0 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
14bf0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
14c00 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
14c10 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
14c20 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14c30 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
14c40 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
14c50 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14c60 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
14c70 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
14c80 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
14c90 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
14ca0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
14cb0 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
14cc0 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
14cd0 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
14ce0 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
14cf0 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
14d00 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f  on.** when the o
14d10 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
14d20 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
14d30 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
14d40 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
14d50 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
14d60 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
14d70 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
14d80 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
14d90 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
14da0 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
14db0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
14dc0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
14dd0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
14de0 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
14df0 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
14e00 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
14e10 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
14e20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14e30 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
14e40 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
14e50 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
14e60 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
14e70 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
14e80 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
14e90 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
14ea0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
14eb0 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
14ec0 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ps..** </dd>.**.
14ed0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14ee0 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
14ef0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14f00 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
14f10 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
14f20 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
14f30 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
14f40 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
14f50 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
14f60 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOG] pre-proces
14f70 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
14f80 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
14f90 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
14fa0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
14fb0 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
14fc0 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
14fd0 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
14fe0 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
14ff0 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
15000 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
15010 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
15020 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
15030 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
15040 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
15050 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
15060 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
15070 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
15080 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
15090 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
150a0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
150b0 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
150c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
150d0 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
150e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
150f0 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
15100 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
15110 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
15120 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
15130 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
15140 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
15150 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
15160 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
15170 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15180 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
15190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
151a0 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
151b0 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
151c0 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
151d0 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
151e0 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
151f0 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
15200 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
15210 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
15220 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
15230 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
15240 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
15250 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
15260 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
15270 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20   In this case.  
15280 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73  An example of us
15290 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66  ing this.** conf
152a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
152b0 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20   can be seen in 
152c0 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67  the "test_sqllog
152d0 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20  .c" source file 
152e0 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69  in.** the canoni
152f0 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  cal SQLite sourc
15300 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e tree.</dd>.**.
15310 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15320 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  IG_MMAP_SIZE]].*
15330 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15340 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a  FIG_MMAP_SIZE.**
15350 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e   <dd>^SQLITE_CON
15360 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61  FIG_MMAP_SIZE ta
15370 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69  kes two 64-bit i
15380 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f  nteger (sqlite3_
15390 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a  int64) values.**
153a0 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65   that are the de
153b0 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20  fault mmap size 
153c0 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75  limit (the defau
153d0 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a  lt setting for.*
153e0 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  * [PRAGMA mmap_s
153f0 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61  ize]) and the ma
15400 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
15410 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a  ap size limit..*
15420 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
15430 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76  etting can be ov
15440 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68  erridden by each
15450 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15460 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69  tion using.** ei
15470 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41  ther the [PRAGMA
15480 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d   mmap_size] comm
15490 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67  and, or by using
154a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
154b0 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
154c0 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20   file control.  
154d0 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  ^(The maximum al
154e0 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
154f0 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e  ** will be silen
15500 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66  tly truncated if
15510 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68   necessary so th
15520 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  at it does not e
15530 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  xceed the.** com
15540 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75  pile-time maximu
15550 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20  m mmap size set 
15560 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
15570 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d  E_MAX_MMAP_SIZE]
15580 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15590 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65  tion.)^.** ^If e
155a0 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74  ither argument t
155b0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
155c0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
155d0 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73  that argument is
155e0 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69  .** changed to i
155f0 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
15600 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b  default..**.** [
15610 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  [SQLITE_CONFIG_W
15620 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a  IN32_HEAPSIZE]].
15630 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
15640 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15650 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  IZE.** <dd>^The 
15660 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15670 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74  N32_HEAPSIZE opt
15680 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
15690 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
156a0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66  is.** compiled f
156b0 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20  or Windows with 
156c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
156d0 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
156e0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a  ocessor macro.**
156f0 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54   defined. ^SQLIT
15700 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
15710 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
15720 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
15730 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
15740 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
15750 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
15760 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
15770 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  heap..** </dl>.*
15780 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15790 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
157a0 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
157b0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
157c0 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
157d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
157e0 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
157f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15800 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
15810 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
15820 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
15830 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
15840 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
15850 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
15860 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
15870 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
15880 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
15890 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
158a0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
158b0 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
158c0 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
158d0 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
158e0 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
158f0 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
15900 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
15910 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
15920 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15930 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
15940 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15950 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
15960 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15970 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
15980 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
15990 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
159a0 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
159b0 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
159c0 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
159d0 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
159e0 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
159f0 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
15a00 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
15a10 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
15a20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
15a30 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
15a40 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
15a50 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
15a60 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
15a70 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
15a80 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
15a90 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
15aa0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
15ab0 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
15ac0 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
15ad0 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
15ae0 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
15af0 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
15b00 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
15b10 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
15b20 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
15b30 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
15b40 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
15b50 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
15b60 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
15b70 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
15b80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15b90 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
15ba0 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
15bb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15bc0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
15bd0 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
15be0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15bf0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
15c00 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
15c10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15c20 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
15c30 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
15c40 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
15c50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15c60 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
15c70 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
15c80 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
15c90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15ca0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
15cb0 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
15cc0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
15cd0 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
15ce0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
15cf0 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
15d00 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
15d10 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
15d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
15d30 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
15d40 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
15d50 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
15d60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15d70 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
15d80 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
15d90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15da0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
15db0 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
15dc0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
15dd0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
15de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15df0 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
15e00 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
15e10 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
15e20 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
15e30 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
15e40 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
15e50 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
15e60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15e70 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
15e80 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
15e90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15ea0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15eb0 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
15ec0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
15ed0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15ee0 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
15ef0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
15f00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15f10 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
15f20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
15f30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15f40 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
15f50 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
15f60 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
15f70 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15f80 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
15f90 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
15fa0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
15fb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15fc0 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
15fd0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
15fe0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
15ff0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16000 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
16010 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
16020 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
16030 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16040 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
16050 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
16060 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16070 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
16080 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
16090 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
160a0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
160b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
160c0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
160d0 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
160e0 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
160f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16100 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
16110 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
16120 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
16130 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16140 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
16150 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
16160 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
16170 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16180 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
16190 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
161a0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
161b0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
161c0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
161d0 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
161e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
161f0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
16200 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
16210 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16220 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
16230 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
16240 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
16250 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16260 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
16270 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
16280 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
16290 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
162a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
162b0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
162c0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
162d0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
162e0 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
162f0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
16300 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16310 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
16320 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
16330 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
16340 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16350 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
16360 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
16370 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
16380 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
16390 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
163a0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
163b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
163c0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
163d0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
163e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
163f0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
16400 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16410 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
16420 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
16430 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
16440 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
16450 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
16460 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
16470 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
16480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16490 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
164a0 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
164b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
164c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
164d0 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
164e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
164f0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
16500 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
16510 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
16520 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16530 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
16540 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16550 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
16560 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
16570 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
16580 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
16590 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
165a0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
165b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
165c0 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
165d0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
165e0 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
165f0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
16600 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
16610 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
16620 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
16630 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
16640 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
16650 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
16660 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
16670 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
16680 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
16690 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
166a0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
166b0 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
166c0 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
166d0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
166e0 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
166f0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
16700 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
16710 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
16720 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
16730 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
16740 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
16750 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
16760 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
16770 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
16780 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
16790 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
167a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
167b0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
167c0 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
167d0 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
167e0 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
167f0 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
16800 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
16810 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
16820 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
16830 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
16840 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
16850 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
16860 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
16870 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
16880 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
16890 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
168a0 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
168b0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
168c0 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
168d0 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
168e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
168f0 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
16900 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
16910 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
16920 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
16930 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
16940 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
16950 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
16960 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
16970 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
16980 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
16990 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
169a0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
169b0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
169c0 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
169d0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
169e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
169f0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
16a00 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
16a10 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
16a20 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
16a30 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
16a40 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
16a50 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
16a60 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
16a70 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
16a80 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
16a90 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
16aa0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
16ab0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16ac0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
16ad0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
16ae0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
16af0 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
16b00 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
16b10 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
16b20 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
16b30 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
16b40 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
16b50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
16b60 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
16b70 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
16b80 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
16b90 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
16ba0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
16bb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16bc0 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
16bd0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
16be0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
16bf0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
16c00 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
16c10 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
16c20 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
16c30 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
16c40 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
16c50 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
16c60 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
16c70 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
16c80 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
16c90 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
16ca0 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
16cb0 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
16cc0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
16cd0 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
16ce0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
16cf0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
16d00 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
16d10 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
16d20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
16d30 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
16d40 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
16d50 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
16d60 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
16d70 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
16d80 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16d90 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
16da0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
16db0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
16dc0 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
16dd0 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
16de0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
16df0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
16e00 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
16e10 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
16e20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
16e30 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
16e40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
16e50 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
16e60 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
16e70 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
16e80 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
16e90 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
16ea0 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
16eb0 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
16ec0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
16ed0 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
16ee0 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
16ef0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
16f00 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
16f10 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
16f20 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
16f30 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
16f40 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
16f50 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
16f60 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
16f70 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
16f80 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
16f90 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
16fa0 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
16fb0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
16fc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
16fd0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
16fe0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
16ff0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
17000 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
17010 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
17020 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
17030 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61  n most SQLite ta
17040 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72  bles (except for
17050 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
17060 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20   tables).** has 
17070 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
17080 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
17090 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
170a0 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
170b0 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
170c0 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
170d0 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
170e0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
170f0 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
17100 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
17110 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
17120 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
17130 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
17140 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
17150 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
17160 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
17170 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
17180 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
17190 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
171a0 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
171b0 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
171c0 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
171d0 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  e sqlite3_last_i
171e0 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69  nsert_rowid(D) i
171f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
17200 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
17210 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63  the .** most rec
17220 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b  ent successful [
17230 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72  INSERT] into a r
17240 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76  owid table or [v
17250 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
17260 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e   on database con
17270 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49  nection D..** ^I
17280 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54  nserts into [WIT
17290 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
172a0 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72  es are not recor
172b0 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  ded..** ^If no s
172c0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
172d0 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  T]s into rowid t
172e0 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76  ables.** have ev
172f0 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
17300 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17310 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68  ection D, .** th
17320 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  en sqlite3_last_
17330 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
17340 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
17350 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
17360 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
17370 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20  in a trigger or 
17380 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61  within a [virtua
17390 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68  l table].** meth
173a0 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f  od, then this ro
173b0 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
173c0 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
173d0 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
173e0 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
173f0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
17400 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
17410 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  hod is running..
17420 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
17430 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
17440 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
17450 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
17460 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
17470 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
17480 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
17490 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
174a0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
174b0 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f  l.** table metho
174c0 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  d began.)^.**.**
174d0 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
174e0 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
174f0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
17500 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
17510 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
17520 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
17530 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
17540 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
17550 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
17560 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
17570 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
17580 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
17590 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
175a0 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
175b0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
175c0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
175d0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
175e0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
175f0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
17600 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
17610 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
17620 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
17630 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
17640 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
17650 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
17660 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
17670 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
17680 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
17690 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
176a0 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
176b0 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
176c0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
176d0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
176e0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
176f0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
17700 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
17710 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
17720 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
17730 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
17740 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
17750 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
17760 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
17770 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
17780 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
17790 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
177a0 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
177b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
177c0 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
177d0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
177e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
177f0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
17800 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
17810 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
17820 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
17830 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17840 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
17850 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
17860 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
17870 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
17880 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
17890 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
178a0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
178b0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
178c0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
178d0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
178e0 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
178f0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17900 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
17910 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
17920 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
17930 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
17940 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
17950 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
17960 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
17970 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
17980 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
17990 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
179a0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
179b0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
179c0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
179d0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
179e0 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
179f0 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
17a00 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
17a10 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
17a20 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
17a30 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
17a40 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
17a50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
17a60 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
17a70 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
17a80 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
17a90 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
17aa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
17ab0 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
17ac0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
17ad0 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
17ae0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
17af0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
17b00 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
17b10 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
17b20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
17b30 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
17b40 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
17b50 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
17b60 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
17b70 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
17b80 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
17b90 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
17ba0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
17bb0 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
17bc0 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
17bd0 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
17be0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
17bf0 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
17c00 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
17c10 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
17c20 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
17c30 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
17c40 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
17c50 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
17c60 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
17c70 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
17c80 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
17c90 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
17ca0 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
17cb0 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
17cc0 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
17cd0 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
17ce0 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
17cf0 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
17d00 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
17d10 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
17d20 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17d30 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
17d40 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
17d50 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
17d60 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
17d70 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
17d80 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
17d90 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
17da0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
17db0 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
17dc0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
17dd0 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
17de0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
17df0 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
17e00 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
17e10 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
17e20 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
17e30 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
17e40 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
17e50 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
17e60 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
17e70 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
17e80 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
17e90 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
17ea0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
17eb0 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
17ec0 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
17ed0 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
17ee0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
17ef0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
17f00 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
17f10 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
17f20 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
17f30 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
17f40 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
17f50 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
17f60 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
17f70 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
17f80 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
17f90 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
17fa0 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
17fb0 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
17fc0 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
17fd0 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
17fe0 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
17ff0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
18000 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
18010 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
18020 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
18030 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
18040 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
18050 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
18060 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
18070 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
18080 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
18090 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
180a0 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
180b0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
180c0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
180d0 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
180e0 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
180f0 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
18100 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
18110 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
18120 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
18130 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
18140 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
18150 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
18160 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
18170 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
18180 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
18190 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
181a0 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
181b0 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
181c0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
181d0 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
181e0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
181f0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
18200 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
18210 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
18220 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
18230 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
18240 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
18250 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
18260 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
18270 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
18280 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
18290 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
182a0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
182b0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
182c0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
182d0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
182e0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
182f0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
18300 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
18310 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
18320 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
18330 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
18340 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
18350 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
18360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18370 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
18380 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
18390 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
183a0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
183b0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
183c0 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
183d0 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
183e0 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
183f0 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
18400 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
18410 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
18420 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
18430 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18440 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
18450 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
18460 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
18470 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
18480 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
18490 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
184a0 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
184b0 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
184c0 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
184d0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
184e0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
184f0 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
18500 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
18510 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
18520 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
18530 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
18540 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
18550 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
18560 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
18570 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
18580 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
18590 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
185a0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
185b0 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
185c0 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
185d0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
185e0 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
185f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
18600 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
18610 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
18620 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
18630 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
18640 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
18650 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
18660 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
18670 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
18680 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
18690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
186a0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
186b0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
186c0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
186d0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
186e0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
186f0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
18700 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
18710 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18720 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
18730 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18740 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
18750 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
18760 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
18770 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
18780 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
18790 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
187a0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
187b0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
187c0 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
187d0 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
187e0 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
187f0 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
18800 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
18810 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
18820 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
18830 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
18840 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
18850 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
18860 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
18870 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
18880 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
18890 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
188a0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
188b0 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
188c0 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
188d0 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
188e0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
188f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
18900 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
18910 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
18920 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
18930 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
18940 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18950 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
18960 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
18970 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
18980 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
18990 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
189a0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
189b0 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
189c0 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
189d0 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
189e0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
189f0 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
18a00 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
18a10 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
18a20 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
18a30 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
18a40 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
18a50 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
18a60 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
18a70 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
18a80 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
18a90 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
18aa0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
18ab0 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
18ac0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
18ad0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
18ae0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
18af0 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
18b00 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
18b10 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
18b20 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
18b30 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
18b40 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
18b50 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
18b60 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18b70 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
18b80 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
18b90 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
18ba0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
18bb0 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
18bc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18bd0 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
18be0 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
18bf0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
18c00 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18c10 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18c20 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
18c30 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
18c40 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
18c50 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
18c60 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
18c70 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
18c80 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
18c90 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
18ca0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
18cb0 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
18cc0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
18cd0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
18ce0 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
18cf0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
18d00 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
18d10 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
18d20 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
18d30 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
18d40 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
18d50 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
18d60 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
18d70 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
18d80 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
18d90 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
18da0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
18db0 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
18dc0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
18dd0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
18de0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
18df0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
18e00 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
18e10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18e20 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
18e30 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
18e40 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
18e50 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
18e60 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
18e70 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
18e80 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
18e90 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
18ea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18eb0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
18ec0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
18ed0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
18ee0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
18ef0 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
18f00 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
18f10 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
18f20 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
18f30 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
18f40 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
18f50 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
18f60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
18f70 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
18f80 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
18f90 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
18fa0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
18fb0 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
18fc0 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
18fd0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
18fe0 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
18ff0 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
19000 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
19010 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
19020 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
19030 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
19040 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
19050 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
19060 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
19070 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
19080 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
19090 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
190a0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
190b0 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
190c0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
190d0 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
190e0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
190f0 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
19100 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
19110 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
19120 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
19130 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
19140 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
19150 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
19160 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
19170 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
19180 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
19190 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
191a0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
191b0 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
191c0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
191d0 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
191e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
191f0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
19200 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
19210 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
19220 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
19230 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
19240 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
19250 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
19260 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
19270 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
19280 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
19290 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
192a0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
192b0 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
192c0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
192d0 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
192e0 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
192f0 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
19300 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
19310 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
19320 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
19330 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
19340 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
19350 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
19360 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
19370 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
19380 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
19390 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
193a0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
193b0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
193c0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
193d0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
193e0 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
193f0 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
19400 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
19410 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
19420 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
19430 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
19440 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
19450 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
19460 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
19470 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
19480 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
19490 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
194a0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
194b0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
194c0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
194d0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
194e0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
194f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
19500 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
19510 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
19520 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
19530 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
19540 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19550 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
19560 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
19570 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
19580 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62  .** KEYWORDS: {b
19590 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
195a0 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64  back} {busy hand
195b0 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ler}.**.** ^The 
195c0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
195d0 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74  dler(D,X,P) rout
195e0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
195f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ack function X.*
19600 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  * that might be 
19610 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
19620 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
19630 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
19640 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
19650 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
19660 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
19670 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
19680 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65  onnection] D whe
19690 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  n another thread
196a0 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
196b0 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63  as the table loc
196c0 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ked..** The sqli
196d0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
196e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
196f0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
19700 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  t.** [sqlite3_bu
19710 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e  sy_timeout()] an
19720 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  d [PRAGMA busy_t
19730 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  imeout]..**.** ^
19740 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
19750 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
19760 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
19770 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
19780 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
19790 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
197a0 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
197b0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
197c0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
197d0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
197e0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
197f0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
19800 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
19810 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19820 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
19830 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
19840 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
19850 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
19860 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
19870 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
19880 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
19890 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
198a0 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
198b0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
198c0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
198d0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
198e0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
198f0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
19900 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ked previously f
19910 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
19920 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
19930 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
19940 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
19950 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
19960 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
19970 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
19980 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
19990 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
199a0 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   is returned.** 
199b0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
199c0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  on..** ^If the c
199d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
199e0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
199f0 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
19a00 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  * is made to acc
19a10 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
19a20 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
19a30 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
19a40 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
19a50 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
19a60 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
19a70 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
19a80 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
19a90 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
19aa0 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
19ab0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
19ac0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
19ad0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
19ae0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
19af0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
19b00 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
19b10 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
19b20 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68  E_BUSY].** to th
19b30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e  e application in
19b40 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
19b50 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68  g the .** busy h
19b60 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
19b70 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
19b80 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
19b90 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
19ba0 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
19bb0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
19bc0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
19bd0 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
19be0 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
19bf0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
19c00 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
19c10 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
19c20 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
19c30 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
19c40 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
19c50 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
19c60 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
19c70 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
19c80 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
19c90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
19ca0 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
19cb0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
19cc0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
19cd0 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
19ce0 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
19cf0 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
19d00 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
19d10 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
19d20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
19d30 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
19d40 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
19d50 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
19d60 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
19d70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
19d80 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
19d90 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
19da0 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
19db0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
19dc0 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
19dd0 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
19de0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
19df0 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
19e00 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
19e10 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
19e20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
19e30 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
19e40 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
19e50 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
19e60 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
19e70 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
19e80 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
19e90 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
19ea0 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
19eb0 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
19ec0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
19ed0 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20  imeout()].** or 
19ee0 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47  evaluating [PRAG
19ef0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d  MA busy_timeout=
19f00 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74  N] will change t
19f10 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  he.** busy handl
19f20 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61  er and thus clea
19f30 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  r any previously
19f40 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65   set busy handle
19f50 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
19f60 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
19f70 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
19f80 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
19f90 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
19fa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
19fb0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
19fc0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49  busy handler.  I
19fd0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a  n other words,.*
19fe0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
19ff0 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  er is not reentr
1a000 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ant.  Any such a
1a010 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
1a020 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
1a030 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
1a040 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
1a050 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
1a060 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a070 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
1a080 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1a090 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1a0a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1a0b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1a0c0 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
1a0d0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
1a0e0 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
1a0f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a100 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
1a110 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  out.**.** ^This 
1a120 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
1a130 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1a140 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
1a150 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
1a160 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
1a170 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
1a180 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
1a190 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
1a1a0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
1a1b0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
1a1c0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
1a1d0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1a1e0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1a1f0 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
1a200 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
1a210 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1a220 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1a230 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
1a240 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
1a250 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
1a260 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
1a270 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
1a280 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
1a290 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
1a2a0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
1a2b0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
1a2c0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
1a2d0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
1a2e0 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
1a2f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
1a300 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1a310 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1a320 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
1a330 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1a340 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
1a350 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
1a360 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
1a370 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
1a380 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
1a390 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1a3a0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
1a3b0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
1a3c0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
1a3d0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
1a3e0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
1a3f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
1a400 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73  so:  [PRAGMA bus
1a410 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e  y_timeout].*/.in
1a420 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1a430 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1a440 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1a450 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1a460 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1a470 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1a480 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
1a490 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1a4a0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1a4b0 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1a4c0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1a4d0 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1a4e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1a4f0 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1a500 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1a510 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1a520 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1a530 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1a540 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1a550 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1a560 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1a570 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1a580 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1a590 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1a5a0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1a5b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1a5c0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1a5d0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1a5e0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1a5f0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1a600 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1a610 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1a620 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1a630 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1a640 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1a650 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1a660 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1a670 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1a680 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1a690 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1a6a0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1a6b0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1a6c0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1a6d0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1a6e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1a6f0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1a700 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1a710 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1a720 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1a730 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1a740 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1a750 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1a760 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1a770 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1a780 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1a790 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1a7a0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1a7b0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1a7c0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1a7d0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1a7e0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1a7f0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1a800 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1a810 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1a820 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1a830 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1a840 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1a850 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1a860 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1a870 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1a880 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1a890 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1a8a0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1a8b0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1a8c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1a8d0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1a8e0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1a8f0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1a900 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1a910 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1a920 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1a930 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1a940 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1a950 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1a960 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1a970 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1a980 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1a990 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1a9a0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1a9b0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1a9c0 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1a9d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a9e0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1a9f0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1aa00 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1aa10 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1aa20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1aa30 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1aa40 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1aa50 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1aa60 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1aa70 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1aa80 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1aa90 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1aaa0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1aab0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1aac0 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1aad0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1aae0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1aaf0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1ab00 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1ab10 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1ab20 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1ab30 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1ab40 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1ab50 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1ab60 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1ab70 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1ab80 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1ab90 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1aba0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1abb0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1abc0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1abd0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1abe0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1abf0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1ac00 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1ac10 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1ac20 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1ac30 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1ac40 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1ac50 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1ac60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ac70 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1ac80 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1ac90 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1aca0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1acb0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1acc0 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1acd0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1ace0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1acf0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1ad00 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1ad10 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1ad20 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1ad30 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1ad40 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1ad50 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1ad60 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1ad70 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1ad80 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1ad90 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1ada0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1adb0 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1adc0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1add0 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1ade0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1adf0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1ae00 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1ae10 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1ae20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1ae30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1ae40 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1ae50 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1ae60 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1ae70 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1ae80 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1ae90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1aea0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1aeb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1aec0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1aed0 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1aee0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1aef0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1af00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1af10 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1af20 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1af30 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1af40 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1af50 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1af60 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1af70 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1af80 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1af90 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1afa0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1afb0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1afc0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1afd0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1afe0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1aff0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1b000 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1b010 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1b020 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1b030 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1b040 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1b050 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1b060 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1b070 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1b080 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1b090 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1b0a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1b0b0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  rrmsg()]..*/.int
1b0c0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1b0d0 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1b0e0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1b0f0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1b100 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1b110 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1b120 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1b130 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1b140 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1b150 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1b160 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1b170 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1b180 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1b190 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1b1a0 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1b1b0 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1b1c0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1b1d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1b1e0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1b1f0 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1b200 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1b210 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1b220 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
1b230 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
1b240 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
1b250 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
1b260 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
1b270 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
1b280 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1b290 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
1b2a0 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
1b2b0 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
1b2c0 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
1b2d0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
1b2e0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
1b2f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b300 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1b310 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1b320 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1b330 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1b340 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1b350 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1b360 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1b370 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1b380 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1b390 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1b3a0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1b3b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1b3c0 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1b3d0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1b3e0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1b3f0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1b400 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1b410 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1b420 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1b430 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1b440 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1b450 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1b460 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1b470 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1b480 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1b490 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1b4a0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1b4b0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1b4c0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1b4d0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1b4e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1b4f0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1b500 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1b510 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1b520 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1b530 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1b540 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1b550 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1b560 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1b570 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1b580 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1b590 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1b5a0 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1b5b0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1b5c0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1b5d0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1b5e0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1b5f0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b600 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1b610 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1b620 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1b630 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1b640 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1b650 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1b660 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1b670 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1b680 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1b690 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1b6a0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1b6b0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1b6c0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1b6d0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1b6e0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1b6f0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1b700 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1b710 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1b720 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1b730 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1b740 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1b750 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1b760 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1b770 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1b780 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1b790 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1b7a0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1b7b0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1b7c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1b7d0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1b7e0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1b7f0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1b800 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1b810 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1b820 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1b830 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1b840 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1b850 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1b860 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1b870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1b880 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1b890 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1b8a0 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1b8b0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1b8c0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1b8d0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1b8e0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1b8f0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1b900 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1b910 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1b920 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1b930 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1b940 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1b950 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1b960 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1b970 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1b980 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1b990 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
1b9a0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
1b9b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
1b9c0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1b9d0 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
1b9e0 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
1b9f0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1ba00 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
1ba10 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
1ba20 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
1ba30 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
1ba40 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
1ba50 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
1ba60 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
1ba70 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
1ba80 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
1ba90 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
1baa0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
1bab0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
1bac0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
1bad0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
1bae0 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
1baf0 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1bb00 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
1bb10 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
1bb20 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
1bb30 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1bb40 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1bb50 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
1bb60 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
1bb70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
1bb80 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1bb90 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
1bba0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
1bbb0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1bbc0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1bbd0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1bbe0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1bbf0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1bc00 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1bc10 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1bc20 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
1bc30 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1bc40 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1bc50 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1bc60 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1bc70 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1bc80 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
1bc90 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
1bca0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
1bcb0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
1bcc0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
1bcd0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
1bce0 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
1bcf0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1bd00 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1bd10 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1bd20 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1bd30 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
1bd40 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
1bd50 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1bd60 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
1bd70 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
1bd80 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
1bd90 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
1bda0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
1bdb0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
1bdc0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1bdd0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1bde0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1bdf0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1be00 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
1be10 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
1be20 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1be30 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
1be40 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
1be50 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
1be60 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
1be70 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
1be80 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
1be90 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
1bea0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
1beb0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
1bec0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
1bed0 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
1bee0 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
1bef0 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
1bf00 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
1bf10 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
1bf20 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
1bf30 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
1bf40 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
1bf50 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
1bf60 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
1bf70 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1bf80 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1bf90 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1bfa0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1bfb0 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1bfc0 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1bfd0 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1bfe0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1bff0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1c000 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1c010 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1c020 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1c030 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1c040 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1c050 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1c060 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1c070 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1c080 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c090 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1c0a0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1c0b0 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1c0c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1c0d0 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1c0e0 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1c0f0 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1c100 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1c110 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1c120 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1c130 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1c140 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1c150 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1c160 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1c170 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1c180 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1c190 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1c1a0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1c1b0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1c1c0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1c1d0 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
1c1e0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1c1f0 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1c200 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1c210 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1c220 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
1c230 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1c240 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1c250 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1c260 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1c270 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1c280 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1c290 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1c2a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1c2b0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1c2c0 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1c2d0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1c2e0 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1c2f0 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1c300 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1c310 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1c320 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1c330 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1c340 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1c350 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1c360 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1c370 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1c380 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1c390 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1c3a0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1c3b0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1c3c0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1c3d0 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1c3e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1c3f0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1c400 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1c410 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1c420 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1c430 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1c440 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1c450 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1c460 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1c470 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1c480 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1c490 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1c4a0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1c4b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1c4c0 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1c4d0 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1c4e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1c4f0 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1c500 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1c510 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1c520 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1c530 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
1c540 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e  lite3_malloc64(N
1c550 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20  ) routine works 
1c560 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c  just like.** sql
1c570 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65  ite3_malloc(N) e
1c580 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1c590 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62  an unsigned 64-b
1c5a0 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  it integer inste
1c5b0 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65  ad.** of a signe
1c5c0 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  d 32-bit integer
1c5d0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1c5e0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1c5f0 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1c600 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1c610 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1c620 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1c630 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1c640 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1c650 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1c660 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1c670 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1c680 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1c690 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1c6a0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1c6b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1c6c0 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1c6d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1c6e0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1c6f0 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1c700 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1c710 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1c720 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1c730 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1c740 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1c750 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1c760 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1c770 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1c780 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1c790 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1c7a0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1c7b0 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1c7c0 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1c7d0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1c7e0 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1c7f0 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1c800 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1c810 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1c820 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1c830 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1c840 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1c850 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1c860 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1c870 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1c880 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65  ealloc(X,N) inte
1c890 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1c8a0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1c8b0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1c8c0 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74  ation X to be at
1c8d0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a   least N bytes..
1c8e0 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72  ** ^If the X par
1c8f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1c900 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a  3_realloc(X,N).*
1c910 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
1c920 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
1c930 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
1c940 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
1c950 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c960 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  N)..** ^If the N
1c970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1c980 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1c990 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  N) is zero or.**
1c9a0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1c9b0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1c9c0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1c9d0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1c9e0 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a  lite3_free(X)..*
1c9f0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1ca00 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1ca10 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
1ca20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ca30 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
1ca40 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
1ca50 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  or NULL if insuf
1ca60 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1ca70 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
1ca80 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a  ^If M is the siz
1ca90 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
1caa0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
1cab0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
1cac0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
1cad0 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
1cae0 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
1caf0 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
1cb00 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
1cb10 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1cb20 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72  (X,N) and the pr
1cb30 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1cb40 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1cb50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1cb60 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  X,N) returns NUL
1cb70 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74  L and N is posit
1cb80 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ive, then the.**
1cb90 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1cba0 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  n is not freed..
1cbb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1cbc0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e  e3_realloc64(X,N
1cbd0 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72  ) interfaces wor
1cbe0 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a  ks the same as.*
1cbf0 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  * sqlite3_reallo
1cc00 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68  c(X,N) except th
1cc10 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74  at N is a 64-bit
1cc20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
1cc30 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
1cc40 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  a 32-bit signed 
1cc50 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
1cc60 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79  If X is a memory
1cc70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76   allocation prev
1cc80 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
1cc90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1cca0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1ccb0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71  3_malloc64(), sq
1ccc0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1ccd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1cce0 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a  loc64(), then.**
1ccf0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1cd00 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  ) returns the si
1cd10 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72  ze of that memor
1cd20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20  y allocation in 
1cd30 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76  bytes..** ^The v
1cd40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1cd50 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1cd60 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65  ) might be large
1cd70 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65  r than the numbe
1cd80 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65  r.** of bytes re
1cd90 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77  quested when X w
1cda0 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  as allocated.  ^
1cdb0 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70  If X is a NULL p
1cdc0 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73  ointer then.** s
1cdd0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1cde0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49  returns zero.  I
1cdf0 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f  f X points to so
1ce00 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20  mething that is 
1ce10 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e  not.** the begin
1ce20 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ning of memory a
1ce30 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66  llocation, or if
1ce40 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20   it points to a 
1ce50 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69  formerly.** vali
1ce60 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
1ce70 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77  ion that has now
1ce80 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65   been freed, the
1ce90 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
1cea0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69  * of sqlite3_msi
1ceb0 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e  ze(X) is undefin
1cec0 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20  ed and possibly 
1ced0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
1cee0 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1cef0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1cf00 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33  alloc(), sqlite3
1cf10 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  _realloc(),.** s
1cf20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1cf30 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
1cf40 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73  ealloc64().** is
1cf50 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
1cf60 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
1cf70 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
1cf80 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
1cf90 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
1cfa0 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
1cfb0 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
1cfc0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1cfd0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
1cfe0 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
1cff0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
1d000 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
1d010 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
1d020 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
1d030 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
1d040 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
1d050 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
1d060 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
1d070 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
1d080 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
1d090 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
1d0a0 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
1d0b0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
1d0c0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
1d0d0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1d0e0 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
1d0f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
1d100 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
1d110 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
1d120 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
1d130 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
1d140 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
1d150 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1d160 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
1d170 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
1d180 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
1d190 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1d1a0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
1d1b0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
1d1c0 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
1d1d0 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
1d1e0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
1d1f0 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
1d200 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
1d210 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1d220 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
1d230 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
1d240 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
1d250 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
1d260 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
1d270 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
1d280 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
1d290 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
1d2a0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
1d2b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1d2c0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1d2d0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1d2e0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
1d2f0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
1d300 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
1d310 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
1d320 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1d330 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
1d340 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1d350 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
1d360 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
1d370 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
1d380 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1d390 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
1d3a0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
1d3b0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
1d3c0 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
1d3d0 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
1d3e0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
1d3f0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
1d400 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1d410 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
1d420 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1d430 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1d440 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1d450 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1d460 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1d470 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
1d480 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1d490 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
1d4a0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1d4b0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1d4c0 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  void*);.sqlite3_
1d4d0 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  uint64 sqlite3_m
1d4e0 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  size(void*);../*
1d4f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1d500 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1d510 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1d520 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1d530 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1d540 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1d550 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1d560 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1d570 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1d580 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1d590 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1d5a0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1d5b0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1d5c0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1d5d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d5e0 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1d5f0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1d600 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1d610 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1d620 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1d630 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1d640 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1d650 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1d660 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1d670 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1d680 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1d690 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1d6a0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1d6b0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1d6c0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1d6d0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1d6e0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1d6f0 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1d700 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1d710 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1d720 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1d730 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d740 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1d750 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1d760 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1d770 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1d780 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1d790 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1d7a0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1d7b0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1d7c0 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1d7d0 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1d7e0 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1d7f0 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1d800 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1d810 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1d820 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1d830 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1d840 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1d850 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1d860 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1d870 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1d880 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1d890 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1d8a0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1d8b0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1d8c0 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1d8d0 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1d8e0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1d8f0 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1d900 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1d910 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1d920 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
1d930 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1d940 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1d950 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
1d960 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1d970 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1d980 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1d990 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1d9a0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1d9b0 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1d9c0 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
1d9d0 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
1d9e0 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
1d9f0 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
1da00 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
1da10 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
1da20 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
1da30 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
1da40 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
1da50 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
1da60 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
1da70 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1da80 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
1da90 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
1daa0 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
1dab0 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
1dac0 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
1dad0 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
1dae0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1daf0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
1db00 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
1db10 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
1db20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
1db30 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
1db40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
1db50 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
1db60 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
1db70 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68  buffer P..** ^Th
1db80 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61  e P parameter ca
1db90 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n be a NULL poin
1dba0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
1dbb0 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20  his routine has 
1dbc0 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75  not been previou
1dbd0 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66  sly called or if
1dbe0 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a   the previous.**
1dbf0 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73   call had N less
1dc00 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e   than one or a N
1dc10 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
1dc20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47  P, then the PRNG
1dc30 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73   is.** seeded us
1dc40 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
1dc50 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65  btained from the
1dc60 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
1dc70 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65  hod of.** the de
1dc80 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1dc90 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
1dca0 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
1dcb0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1dcc0 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
1dcd0 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61   1 or more and a
1dce0 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74  .** non-NULL P t
1dcf0 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72  hen the pseudo-r
1dd00 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1dd10 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1dd20 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1dd30 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1dd40 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1dd50 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1dd60 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
1dd70 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
1dd80 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
1dd90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1dda0 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1ddb0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
1ddc0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1ddd0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
1dde0 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
1ddf0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
1de00 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
1de10 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1de20 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
1de30 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
1de40 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
1de50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1de60 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1de70 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
1de80 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
1de90 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
1dea0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1deb0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
1dec0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ded0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
1dee0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1def0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1df00 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
1df10 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
1df20 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
1df30 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
1df40 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
1df50 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
1df60 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
1df70 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
1df80 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1df90 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1dfa0 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
1dfb0 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
1dfc0 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
1dfd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1dfe0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
1dff0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1e000 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
1e010 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
1e020 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
1e030 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
1e040 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
1e050 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
1e060 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
1e070 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
1e080 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
1e090 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
1e0a0 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
1e0b0 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
1e0c0 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
1e0d0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
1e0e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e0f0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
1e100 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
1e110 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
1e120 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
1e130 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1e140 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
1e150 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e160 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1e170 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1e180 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
1e190 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1e1a0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1e1b0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
1e1c0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
1e1d0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1e1e0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
1e1f0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
1e200 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
1e210 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
1e220 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1e230 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
1e240 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1e250 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1e260 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1e270 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
1e280 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1e290 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1e2a0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1e2b0 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
1e2c0 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
1e2d0 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
1e2e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1e2f0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1e300 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1e310 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
1e320 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
1e330 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1e340 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1e350 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
1e360 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1e370 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
1e380 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1e390 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
1e3a0 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
1e3b0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1e3c0 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
1e3d0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1e3e0 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
1e3f0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
1e400 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
1e410 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1e420 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
1e430 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1e440 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
1e450 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
1e460 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
1e470 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1e480 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1e490 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1e4a0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
1e4b0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1e4c0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1e4d0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1e4e0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
1e4f0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
1e500 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
1e510 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
1e520 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
1e530 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
1e540 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
1e550 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
1e560 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
1e570 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
1e580 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
1e590 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
1e5a0 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
1e5b0 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
1e5c0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
1e5d0 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
1e5e0 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
1e5f0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
1e600 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1e610 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1e620 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
1e630 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1e640 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
1e650 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
1e660 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
1e670 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
1e680 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
1e690 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
1e6a0 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
1e6b0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
1e6c0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
1e6d0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
1e6e0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
1e6f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e700 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
1e710 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1e720 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
1e730 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
1e740 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
1e750 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1e760 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
1e770 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
1e780 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
1e790 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
1e7a0 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
1e7b0 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
1e7c0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
1e7d0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
1e7e0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
1e7f0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
1e800 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
1e810 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
1e820 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
1e830 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
1e840 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
1e850 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
1e860 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1e870 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
1e880 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
1e890 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
1e8a0 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
1e8b0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
1e8c0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
1e8d0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
1e8e0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
1e8f0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
1e900 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
1e910 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
1e920 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
1e930 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
1e940 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
1e950 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
1e960 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1e970 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
1e980 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
1e990 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
1e9a0 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
1e9b0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
1e9c0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
1e9d0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
1e9e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
1e9f0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
1ea00 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
1ea10 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
1ea20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
1ea30 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
1ea40 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
1ea50 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
1ea60 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
1ea70 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
1ea80 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
1ea90 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
1eaa0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
1eab0 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
1eac0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
1ead0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
1eae0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
1eaf0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
1eb00 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
1eb10 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
1eb20 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
1eb30 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
1eb40 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
1eb50 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
1eb60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
1eb70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1eb80 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1eb90 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1eba0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1ebb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1ebc0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1ebd0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ebe0 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
1ebf0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1ec00 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1ec10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1ec20 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1ec30 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1ec40 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1ec50 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1ec60 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1ec70 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
1ec80 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1ec90 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
1eca0 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
1ecb0 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
1ecc0 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
1ecd0 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
1ece0 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
1ecf0 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
1ed00 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
1ed10 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
1ed20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
1ed30 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
1ed40 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
1ed50 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ed60 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
1ed70 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
1ed80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1ed90 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
1eda0 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
1edb0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1edc0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
1edd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1ede0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1edf0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
1ee00 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
1ee10 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
1ee20 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
1ee30 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
1ee40 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
1ee50 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
1ee60 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1ee70 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
1ee80 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
1ee90 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
1eea0 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
1eeb0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1eec0 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
1eed0 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
1eee0 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
1eef0 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
1ef00 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
1ef10 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
1ef20 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1ef30 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1ef40 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
1ef50 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
1ef60 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
1ef70 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1ef80 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
1ef90 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1efa0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1efb0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
1efc0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
1efd0 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
1efe0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
1eff0 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
1f000 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
1f010 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
1f020 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
1f030 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1f040 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
1f050 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
1f060 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
1f070 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1f080 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
1f090 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
1f0a0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1f0b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
1f0c0 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
1f0d0 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
1f0e0 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
1f0f0 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
1f100 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
1f110 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
1f120 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
1f130 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
1f140 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f150 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1f160 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1f170 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1f180 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1f190 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1f1a0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1f1b0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1f1c0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1f1d0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1f1e0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1f1f0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
1f200 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1f210 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1f220 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1f230 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
1f240 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
1f250 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
1f260 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
1f270 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
1f280 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
1f290 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1f2a0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1f2b0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1f2c0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
1f2d0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
1f2e0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
1f2f0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
1f300 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
1f310 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
1f320 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
1f330 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
1f340 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
1f350 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
1f360 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
1f370 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
1f380 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
1f390 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
1f3a0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
1f3b0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
1f3c0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
1f3d0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
1f3e0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
1f3f0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1f400 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1f410 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
1f420 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
1f430 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1f440 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
1f450 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1f460 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1f470 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1f480 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1f490 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1f4a0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1f4b0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1f4c0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
1f4d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1f4e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f4f0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
1f500 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
1f510 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
1f520 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
1f530 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
1f540 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
1f550 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
1f560 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
1f570 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
1f580 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
1f590 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1f5a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f5b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f5c0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1f5d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1f5e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1f5f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f600 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1f610 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1f620 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1f630 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1f640 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f650 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1f660 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f670 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f680 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f690 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1f6a0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1f6b0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1f6c0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1f6d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f6e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1f6f0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1f700 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f710 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f720 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f730 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1f740 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1f750 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1f760 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1f770 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f780 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1f790 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1f7a0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1f7b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f7c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f7d0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1f7e0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1f7f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1f800 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f810 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f820 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1f830 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1f840 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1f850 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f860 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f870 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1f880 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1f890 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f8a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f8b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f8c0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1f8d0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1f8e0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1f8f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f910 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1f920 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1f930 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f940 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f950 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f960 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1f970 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1f980 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1f990 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f9a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f9b0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1f9c0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1f9d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f9e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f9f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1fa00 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1fa10 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1fa20 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1fa30 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fa40 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1fa50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1fa60 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1fa70 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1fa80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fa90 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1faa0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1fab0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1fac0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1fad0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1fae0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1faf0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1fb00 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1fb10 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1fb20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1fb30 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1fb40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1fb50 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1fb60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1fb70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fb80 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1fb90 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1fba0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1fbb0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1fbc0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1fbd0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1fbe0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1fbf0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1fc00 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1fc10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fc20 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1fc30 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1fc40 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1fc50 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1fc60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fc70 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1fc80 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1fc90 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1fca0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1fcb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fcc0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1fcd0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1fce0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1fcf0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1fd00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fd10 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1fd20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1fd30 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1fd40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fd50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fd60 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1fd70 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1fd80 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1fd90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fda0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fdb0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1fdc0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1fdd0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1fde0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1fdf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fe00 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1fe10 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1fe20 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1fe30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fe40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1fe50 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1fe60 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1fe70 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1fe80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1fe90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1fea0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1feb0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1fec0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1fed0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1fee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1fef0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1ff00 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1ff10 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1ff20 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1ff30 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1ff40 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1ff50 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1ff60 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1ff70 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1ff80 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
1ff90 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
1ffa0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
1ffb0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
1ffc0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
1ffd0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
1ffe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1fff0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
20000 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
20010 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
20020 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
20030 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
20040 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20050 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
20060 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
20070 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
20080 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
20090 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
200a0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
200b0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
200c0 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
200d0 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
200e0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
200f0 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
20100 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
20110 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
20120 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
20130 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
20140 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
20150 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
20160 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
20170 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
20180 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
20190 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
201a0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
201b0 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
201c0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
201d0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
201e0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
201f0 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
20200 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
20210 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
20220 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
20230 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
20240 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
20250 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
20260 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
20270 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
20280 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
20290 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
202a0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
202b0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
202c0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
202d0 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
202e0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
202f0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
20300 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
20310 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
20320 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
20330 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
20340 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
20350 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
20360 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
20370 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
20380 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
20390 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
203a0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
203b0 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
203c0 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
203d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
203e0 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
203f0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
20400 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
20410 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
20420 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
20430 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
20440 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
20450 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
20460 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
20470 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
20480 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
20490 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
204a0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
204b0 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
204c0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
204d0 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
204e0 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
204f0 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
20500 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
20510 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
20520 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
20530 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
20540 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
20550 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
20560 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
20570 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
20580 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
20590 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
205a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
205b0 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
205c0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
205d0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
205e0 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
205f0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
20600 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
20610 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  te..*/.void *sql
20620 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
20630 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
20640 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
20650 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
20660 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
20670 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
20680 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
20690 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
206a0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
206b0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
206c0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
206d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
206e0 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
206f0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
20700 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
20710 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
20720 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
20730 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
20740 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
20750 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
20760 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
20770 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
20780 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
20790 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
207a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
207b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
207c0 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
207d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
207e0 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
207f0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
20800 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
20810 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
20820 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
20830 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
20840 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
20850 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
20860 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
20870 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
20880 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
20890 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
208a0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
208b0 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61  is the approxima
208c0 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  te number of .**
208d0 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
208e0 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
208f0 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
20900 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
20910 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
20920 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
20930 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69  back X.  ^If N i
20940 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  s less than one 
20950 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
20960 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20  s.** handler is 
20970 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
20980 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
20990 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
209a0 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
209b0 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
209c0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
209d0 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
209e0 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
209f0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
20a00 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
20a10 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
20a20 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
20a30 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
20a40 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
20a50 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
20a60 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
20a70 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
20a80 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
20a90 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
20aa0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
20ab0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
20ac0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
20ad0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
20ae0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
20af0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
20b00 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
20b10 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
20b20 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
20b30 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
20b40 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
20b50 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
20b60 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
20b70 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
20b80 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
20b90 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
20ba0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20bb0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
20bc0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
20bd0 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
20be0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20bf0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
20c00 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
20c10 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
20c20 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
20c30 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
20c40 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
20c50 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
20c60 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
20c70 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
20c80 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
20c90 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
20ca0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
20cb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20cc0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
20cd0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
20ce0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
20cf0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
20d00 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
20d10 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
20d20 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
20d30 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
20d40 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
20d50 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
20d60 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
20d70 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
20d80 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
20d90 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
20da0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
20db0 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
20dc0 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
20dd0 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
20de0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
20df0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
20e00 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
20e10 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
20e20 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
20e30 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
20e40 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
20e50 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
20e60 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
20e70 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
20e80 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
20e90 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
20ea0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
20eb0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
20ec0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
20ed0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
20ee0 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
20ef0 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
20f00 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
20f10 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
20f20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
20f30 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
20f40 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
20f50 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
20f60 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
20f70 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
20f80 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
20f90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20fa0 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
20fb0 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
20fc0 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
20fd0 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
20fe0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
20ff0 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
21000 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
21010 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
21020 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
21030 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
21040 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
21050 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46  ding will be UTF
21060 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  -8 for databases
21070 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
21080 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
21090 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
210a0 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66  _v2().  ^The def
210b0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
210c0 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63  r databases.** c
210d0 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c  reated using sql
210e0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69  ite3_open16() wi
210f0 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20  ll be UTF-16 in 
21100 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
21110 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  order..**.** Whe
21120 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
21130 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
21140 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
21150 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
21160 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
21170 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
21180 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
21190 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
211a0 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
211b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
211c0 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
211d0 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
211e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
211f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21200 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
21210 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
21220 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
21230 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
21240 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
21250 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
21260 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
21270 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
21280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21290 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
212a0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
212b0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
212c0 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
212d0 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
212e0 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
212f0 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
21300 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
21310 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
21320 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
21330 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
21340 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
21350 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
21360 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
21370 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
21380 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
21390 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
213a0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
213b0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
213c0 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
213d0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
213e0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
213f0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
21400 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
21410 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
21420 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
21430 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
21440 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
21450 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
21460 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
21470 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
21480 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
21490 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
214a0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
214b0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
214c0 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
214d0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
214e0 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
214f0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
21500 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
21510 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
21520 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
21530 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
21540 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
21550 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
21560 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
21570 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
21580 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
21590 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
215a0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
215b0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
215c0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
215d0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
215e0 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
215f0 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
21600 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
21610 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
21620 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
21630 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
21640 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
21650 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
21660 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
21670 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
21680 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
21690 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
216a0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
216b0 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
216c0 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
216d0 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
216e0 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
216f0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
21700 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
21710 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
21720 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
21730 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
21740 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
21750 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
21760 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
21770 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21780 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
21790 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
217a0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
217b0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
217c0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
217d0 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
217e0 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
217f0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
21800 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
21810 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
21820 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
21830 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
21840 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21850 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
21860 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
21870 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
21880 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
21890 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
218a0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
218b0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
218c0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
218d0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
218e0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
218f0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
21900 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21910 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
21920 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
21930 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
21940 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
21950 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
21960 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
21970 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
21980 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
21990 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
219a0 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
219b0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
219c0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
219d0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
219e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
219f0 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
21a00 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
21a10 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
21a20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
21a30 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
21a40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
21a50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
21a60 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
21a70 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
21a80 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
21a90 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
21aa0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
21ab0 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
21ac0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
21ad0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
21ae0 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
21af0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
21b00 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
21b10 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
21b20 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
21b30 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
21b40 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
21b50 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
21b60 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
21b70 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
21b80 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
21b90 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
21ba0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
21bb0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
21bc0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
21bd0 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
21be0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
21bf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21c00 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
21c10 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
21c20 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
21c30 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
21c40 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
21c50 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
21c60 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
21c70 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
21c80 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
21c90 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
21ca0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
21cb0 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
21cc0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
21cd0 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
21ce0 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
21cf0 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
21d00 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
21d10 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
21d20 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
21d30 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
21d40 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
21d50 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
21d60 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
21d70 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
21d80 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
21d90 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
21da0 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
21db0 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
21dc0 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
21dd0 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
21de0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21df0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
21e00 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
21e10 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
21e20 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
21e30 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
21e40 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
21e50 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
21e60 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
21e70 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
21e80 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
21e90 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
21ea0 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
21eb0 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
21ec0 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
21ed0 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
21ee0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
21ef0 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
21f00 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
21f10 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
21f20 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68  et in the fourth
21f30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
21f40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20  ite3_open_v2(), 
21f50 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  or if it has.** 
21f60 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f  been enabled glo
21f70 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20  bally using the 
21f80 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
21f90 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20  RI] option with 
21fa0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
21fb0 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64  config()] method
21fc0 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49   or by the [SQLI
21fd0 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70  TE_USE_URI] comp
21fe0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
21ff0 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65  .** As of SQLite
22000 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
22010 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  URI filename int
22020 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74  erpretation is t
22030 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20  urned off.** by 
22040 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74  default, but fut
22050 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
22060 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61  SQLite might ena
22070 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  ble URI filename
22080 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69  .** interpretati
22090 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
220a0 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61  See "[URI filena
220b0 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69  mes]" for additi
220c0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
220d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66  ion..**.** URI f
220e0 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72  ilenames are par
220f0 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  sed according to
22100 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74   RFC 3986. ^If t
22110 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20  he URI contains 
22120 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c  an.** authority,
22130 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65   then it must be
22140 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79   either an empty
22150 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73   string or the s
22160 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c  tring .** "local
22170 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61  host". ^If the a
22180 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20  uthority is not 
22190 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
221a0 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20  or "localhost", 
221b0 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20  an .** error is 
221c0 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
221d0 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61  caller. ^The fra
221e0 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  gment component 
221f0 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a  of a URI, if .**
22200 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e   present, is ign
22210 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ored..**.** ^SQL
22220 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74  ite uses the pat
22230 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74  h component of t
22240 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61  he URI as the na
22250 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66  me of the disk f
22260 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e  ile.** which con
22270 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61  tains the databa
22280 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  se. ^If the path
22290 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27   begins with a '
222a0 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a  /' character, .*
222b0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  * then it is int
222c0 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61  erpreted as an a
222d0 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49  bsolute path. ^I
222e0 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20  f the path does 
222f0 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69  not begin .** wi
22300 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e  th a '/' (meanin
22310 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  g that the autho
22320 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20  rity section is 
22330 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
22340 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68   URI).** then th
22350 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70  e path is interp
22360 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74  reted as a relat
22370 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28  ive path. .** ^(
22380 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20  On windows, the 
22390 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20  first component 
223a0 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  of an absolute p
223b0 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69  ath .** is a dri
223c0 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  ve specification
223d0 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a   (e.g. "C:").)^.
223e0 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
223f0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
22400 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
22410 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
22420 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
22430 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
22440 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
22450 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
22460 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
22470 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
22480 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
22490 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
224a0 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69   and its built-i
224b0 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70  n [VFSes] interp
224c0 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ret the.** follo
224d0 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d  wing query param
224e0 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
224f0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
22500 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
22510 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
22520 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
22530 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
22540 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
22550 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
22560 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
22570 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
22580 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
22590 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
225a0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
225b0 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
225c0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
225d0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
225e0 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
225f0 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
22600 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
22610 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
22620 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
22630 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
22640 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
22650 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
22660 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
22670 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
22680 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
22690 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
226a0 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
226b0 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
226c0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
226d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
226e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
226f0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
22700 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
22710 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
22720 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
22730 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
22740 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
22750 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
22760 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
22770 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
22780 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
22790 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
227a0 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
227b0 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
227c0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
227d0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
227e0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
227f0 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
22800 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
22810 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
22820 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
22830 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
22840 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
22850 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
22860 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22870 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
22880 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
22890 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
228a0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
228b0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
228c0 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
228d0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
228e0 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
228f0 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
22900 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
22910 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
22920 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
22930 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
22940 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
22950 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
22960 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
22970 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
22980 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
22990 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
229a0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
229b0 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
229c0 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
229d0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
229e0 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
229f0 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
22a00 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
22a10 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
22a20 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
22a30 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
22a40 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
22a50 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
22a60 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
22a70 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
22a80 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
22a90 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
22aa0 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
22ab0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
22ac0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
22ad0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
22ae0 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
22af0 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
22b00 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
22b10 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
22b20 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
22b30 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
22b40 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
22b50 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
22b60 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
22b70 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
22b80 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
22b90 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
22ba0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
22bb0 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
22bc0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
22bd0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
22be0 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
22bf0 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
22c00 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
22c10 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
22c20 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
22c30 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
22c40 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
22c50 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
22c60 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
22c70 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
22c80 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
22c90 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
22ca0 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
22cb0 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
22cc0 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
22cd0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
22ce0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
22cf0 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
22d00 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
22d10 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
22d20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
22d30 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
22d40 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68   indicates wheth
22d50 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a  er or not the.**
22d60 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20       [powersafe 
22d70 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65  overwrite] prope
22d80 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73  rty does or does
22d90 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68   not apply to th
22da0 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65  e.**     storage
22db0 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20   media on which 
22dc0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
22dd0 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a  e resides..**.**
22de0 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
22df0 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
22e00 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
22e10 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
22e20 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
22e30 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
22e40 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
22e50 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
22e60 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
22e70 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
22e80 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
22e90 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
22ea0 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
22eb0 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
22ec0 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
22ed0 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
22ee0 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
22ef0 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
22f00 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
22f10 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
22f20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
22f30 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
22f40 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
22f50 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
22f60 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
22f70 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
22f80 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
22f90 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
22fa0 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
22fb0 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
22fc0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
22fd0 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
22fe0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22ff0 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
23000 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
23010 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
23020 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
23030 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
23040 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
23050 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
23060 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
23070 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
23080 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
23090 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
230a0 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
230b0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
230c0 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
230d0 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
230e0 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
230f0 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
23100 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
23110 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
23120 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
23130 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
23140 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
23150 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
23160 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
23170 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
23180 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
23190 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
231a0 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
231b0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
231c0 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
231d0 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
231e0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
231f0 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
23200 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
23210 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
23220 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
23230 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
23240 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
23250 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
23260 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
23270 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
23280 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
23290 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
232a0 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
232b0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
232c0 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
232d0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
232e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
232f0 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
23300 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
23310 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
23320 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
23330 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
23340 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
23350 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
23360 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
23370 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
23380 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
23390 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
233a0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
233b0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
233c0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
233d0 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
233e0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
233f0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23400 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
23410 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
23420 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
23430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
23440 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
23450 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
23460 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
23470 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
23480 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
23490 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
234a0 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
234b0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
234c0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
234d0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
234e0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
234f0 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
23500 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
23510 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
23520 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
23530 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
23540 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
23550 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
23560 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
23570 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
23580 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
23590 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
235a0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
235b0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
235c0 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
235d0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
235e0 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
235f0 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
23600 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
23610 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
23620 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
23630 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
23640 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
23650 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
23660 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
23670 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
23680 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
23690 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
236a0 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
236b0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
236c0 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
236d0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
236e0 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
236f0 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
23700 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
23710 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
23720 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
23730 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
23740 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
23750 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
23760 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
23770 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
23780 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
23790 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
237a0 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
237b0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
237c0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
237d0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
237e0 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
237f0 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
23800 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
23810 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
23820 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
23830 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
23840 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
23850 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
23860 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
23870 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
23880 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
23890 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
238a0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
238b0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
238c0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
238d0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
238e0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
238f0 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
23900 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
23910 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
23920 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
23930 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
23940 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
23950 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
23960 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
23970 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
23980 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
23990 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
239a0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
239b0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
239c0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
239d0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
239e0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
239f0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
23a00 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
23a10 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
23a20 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
23a30 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
23a40 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
23a50 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
23a60 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
23a70 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
23a80 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
23a90 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
23aa0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
23ab0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
23ac0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
23ad0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
23ae0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
23af0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
23b00 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
23b10 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
23b20 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
23b30 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
23b40 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
23b50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
23b60 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
23b70 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
23b80 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
23b90 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
23ba0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
23bb0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
23bc0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
23bd0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
23be0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
23bf0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
23c00 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
23c10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23c20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
23c30 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
23c40 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
23c50 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
23c60 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
23c70 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
23c80 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
23c90 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
23ca0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
23cb0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
23cc0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
23cd0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
23ce0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
23cf0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
23d00 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
23d10 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
23d20 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
23d30 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
23d40 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
23d50 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
23d60 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
23d70 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
23d80 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
23d90 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
23da0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
23db0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
23dc0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
23dd0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
23de0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
23df0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
23e00 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
23e10 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
23e20 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
23e30 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
23e40 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
23e50 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
23e60 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
23e70 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
23e80 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
23e90 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
23ea0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
23eb0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
23ec0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
23ed0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
23ee0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
23ef0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
23f00 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
23f10 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
23f20 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
23f30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23f40 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
23f50 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
23f60 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
23f70 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
23f80 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
23f90 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
23fa0 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
23fb0 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
23fc0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
23fd0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
23fe0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
23ff0 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
24000 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
24010 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
24020 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
24030 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
24040 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
24050 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
24060 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
24070 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
24080 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
24090 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
240a0 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
240b0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
240c0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
240d0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
240e0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
240f0 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
24100 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
24110 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
24120 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
24130 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
24140 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
24150 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
24160 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
24170 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
24180 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
24190 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
241a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
241b0 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
241c0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
241d0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
241e0 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
241f0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
24200 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
24210 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
24220 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
24230 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
24240 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
24250 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
24260 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
24270 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
24280 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
24290 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
242a0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
242b0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
242c0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
242d0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
242e0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
242f0 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
24300 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
24310 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
24320 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
24330 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
24340 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
24350 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
24360 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
24370 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
24380 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
24390 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
243a0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
243b0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
243c0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
243d0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
243e0 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
243f0 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
24400 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
24410 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
24420 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
24430 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
24440 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
24450 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
24460 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
24470 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
24480 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
24490 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
244a0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
244b0 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
244c0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
244d0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
244e0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
244f0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
24500 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
24510 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
24520 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
24530 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
24540 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
24550 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
24560 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
24570 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
24580 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
24590 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
245a0 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
245b0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
245c0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
245d0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
245e0 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
245f0 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
24600 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
24610 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
24620 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
24630 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
24640 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
24650 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
24660 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
24670 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
24680 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
24690 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
246a0 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
246b0 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
246c0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
246d0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
246e0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
246f0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
24700 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
24710 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
24720 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
24730 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
24740 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24750 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
24760 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
24770 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
24780 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
24790 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
247a0 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
247b0 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
247c0 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
247d0 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
247e0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
247f0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
24800 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
24810 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
24820 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
24830 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
24840 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
24850 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
24860 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
24870 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
24880 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
24890 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
248a0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
248b0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
248c0 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
248d0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
248e0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
248f0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
24900 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
24910 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
24920 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
24930 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
24940 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
24950 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
24960 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
24970 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
24980 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
24990 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
249a0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
249b0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
249c0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
249d0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
249e0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
249f0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
24a00 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
24a10 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
24a20 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
24a30 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
24a40 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
24a50 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
24a60 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
24a70 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
24a80 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
24a90 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
24aa0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
24ab0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
24ac0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
24ad0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
24ae0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
24af0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
24b00 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
24b10 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
24b20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
24b30 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
24b40 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
24b50 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
24b60 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
24b70 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
24b80 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
24b90 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
24ba0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
24bb0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
24bc0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
24bd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
24be0 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
24bf0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
24c00 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
24c10 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
24c20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
24c30 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
24c40 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
24c50 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
24c60 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
24c70 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
24c80 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
24c90 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
24ca0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
24cb0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
24cc0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
24cd0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
24ce0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
24cf0 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
24d00 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
24d10 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
24d20 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
24d30 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
24d40 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
24d50 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
24d60 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
24d70 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
24d80 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
24d90 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
24da0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
24db0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
24dc0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
24dd0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
24de0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
24df0 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
24e00 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
24e10 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
24e20 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
24e30 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
24e40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24e50 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
24e60 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
24e70 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
24e80 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
24e90 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
24ea0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
24eb0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
24ec0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
24ed0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
24ee0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
24ef0 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
24f00 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
24f10 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
24f20 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
24f30 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
24f40 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
24f50 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
24f60 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
24f70 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
24f80 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
24f90 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
24fa0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
24fb0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
24fc0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
24fd0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
24fe0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
24ff0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
25000 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
25010 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
25020 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
25030 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
25040 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
25050 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
25060 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
25070 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
25080 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
25090 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
250a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
250b0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
250c0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
250d0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
250e0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
250f0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
25100 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
25110 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
25120 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
25130 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
25140 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
25150 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
25160 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
25170 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
25180 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
25190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
251a0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
251b0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
251c0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
251d0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
251e0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
251f0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
25200 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
25210 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
25220 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
25230 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
25240 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
25250 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
25260 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
25270 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
25280 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
25290 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
252a0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
252b0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
252c0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
252d0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
252e0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
252f0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
25300 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
25310 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
25320 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
25330 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
25340 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
25350 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
25360 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
25370 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
25380 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
25390 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
253a0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
253b0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
253c0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
253d0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
253e0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
253f0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
25400 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
25410 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
25420 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
25430 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
25440 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
25450 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
25460 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
25470 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
25480 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
25490 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
254a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
254b0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
254c0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
254d0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
254e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
254f0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
25500 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
25510 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
25520 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
25530 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
25540 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
25550 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
25560 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
25570 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
25580 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
25590 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
255a0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
255b0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
255c0 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
255d0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
255e0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
255f0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
25600 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
25610 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
25620 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
25630 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
25640 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
25650 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
25660 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
25670 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
25680 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
25690 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
256a0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
256b0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
256c0 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
256d0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
256e0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
256f0 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
25700 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
25710 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
25720 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
25730 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
25740 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
25750 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
25760 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
25770 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
25780 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
25790 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
257a0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
257b0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
257c0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
257d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
257e0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
257f0 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
25800 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
25810 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
25820 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
25830 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
25840 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
25850 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
25860 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
25870 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
25880 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
25890 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
258a0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
258b0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
258c0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
258d0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
258e0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
258f0 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
25900 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
25910 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
25920 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
25930 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
25940 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
25950 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
25960 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
25970 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
25980 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
25990 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
259a0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
259b0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
259c0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
259d0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
259e0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
259f0 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
25a00 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
25a10 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
25a20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
25a30 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
25a40 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
25a50 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
25a60 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
25a70 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
25a80 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
25a90 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
25aa0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
25ab0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
25ac0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
25ad0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
25ae0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
25af0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
25b00 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
25b10 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
25b20 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
25b30 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
25b40 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
25b50 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
25b60 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
25b70 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
25b80 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
25b90 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
25ba0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
25bb0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
25bc0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
25bd0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
25be0 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
25bf0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
25c00 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
25c10 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
25c20 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
25c30 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
25c40 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
25c50 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
25c60 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
25c70 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
25c80 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
25c90 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
25ca0 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
25cb0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
25cc0 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
25cd0 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
25ce0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
25cf0 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
25d00 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
25d10 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
25d20 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
25d30 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
25d40 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
25d50 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
25d60 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
25d70 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
25d80 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
25d90 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
25da0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25db0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
25dc0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25dd0 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
25de0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
25df0 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
25e00 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
25e10 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
25e20 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
25e30 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
25e40 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
25e50 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25e60 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
25e70 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
25e80 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
25e90 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25ea0 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
25eb0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25ec0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
25ed0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
25ee0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
25ef0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
25f00 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
25f10 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
25f20 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
25f30 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
25f40 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
25f50 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
25f60 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
25f70 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
25f80 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
25f90 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
25fa0 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
25fb0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
25fc0 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
25fd0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25fe0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
25ff0 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
26000 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
26010 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
26020 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
26030 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
26040 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
26050 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
26060 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26070 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
26080 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
26090 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
260a0 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
260b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
260c0 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
260d0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
260e0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
260f0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
26100 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
26110 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
26120 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
26130 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
26140 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
26150 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
26160 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
26170 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
26180 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
26190 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
261a0 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
261b0 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
261c0 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
261d0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
261e0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
261f0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26200 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
26210 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26220 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
26230 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
26240 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
26250 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26260 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
26270 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26280 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
26290 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
262a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
262b0 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
262c0 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
262d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
262e0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
262f0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
26300 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
26310 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
26320 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
26330 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26340 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
26350 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
26360 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
26370 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
26380 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
26390 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
263a0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
263b0 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
263c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
263d0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
263e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
263f0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
26400 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
26410 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
26420 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
26430 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
26440 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
26450 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26460 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
26470 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26480 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
26490 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
264a0 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
264b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
264c0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
264d0 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ADS]] ^(<dt>SQLI
264e0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
264f0 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20  THREADS</dt>.** 
26500 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26510 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69  number of auxili
26520 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61  ary worker threa
26530 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65  ds that a single
26540 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
26550 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61  atement] may sta
26560 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rt.</dd>)^.** </
26570 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
26580 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
26590 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
265a0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
265b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
265c0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
265d0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
265e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
265f0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
26600 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
26610 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
26620 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
26630 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
26640 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26650 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
26660 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
26670 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26680 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
26690 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
266a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
266b0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
266c0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
266d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
266e0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
266f0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
26700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26710 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
26720 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
26730 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26740 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
26750 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
26760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26770 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
26780 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
26790 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
267a0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
267b0 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20  READS           
267c0 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  11../*.** CAPI3R
267d0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
267e0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
267f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
26800 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
26810 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
26820 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
26830 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
26840 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
26850 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
26860 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
26870 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
26880 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
26890 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
268a0 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
268b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
268c0 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
268d0 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
268e0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
268f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
26900 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
26910 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
26920 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
26930 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
26940 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
26950 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
26960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
26970 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
26980 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
26990 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
269a0 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
269b0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
269c0 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
269d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
269e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
269f0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
26a00 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
26a10 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
26a20 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
26a30 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26a40 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
26a50 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
26a60 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
26a70 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
26a80 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
26a90 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
26aa0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
26ab0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
26ac0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
26ad0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
26ae0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
26af0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
26b00 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
26b10 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
26b20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
26b30 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
26b40 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
26b50 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
26b60 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
26b70 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
26b80 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
26b90 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
26ba0 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
26bb0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
26bc0 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
26bd0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
26be0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
26bf0 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
26c00 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
26c10 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
26c20 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
26c30 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
26c40 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
26c50 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
26c60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
26c70 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
26c80 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
26c90 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
26ca0 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20  erminator bytes 
26cb0 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51  as this saves SQ
26cc0 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67  Lite from having
26cd0 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f   to.** make a co
26ce0 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20  py of the input 
26cf0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
26d00 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
26d10 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
26d20 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
26d30 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
26d40 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
26d50 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
26d60 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
26d70 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
26d80 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
26d90 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
26da0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
26db0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
26dc0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
26dd0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
26de0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
26df0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
26e00 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
26e10 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
26e20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26e30 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
26e40 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
26e50 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
26e60 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
26e70 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
26e80 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
26e90 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
26ea0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
26eb0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
26ec0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
26ed0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
26ee0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
26ef0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
26f00 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
26f10 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
26f20 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
26f30 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
26f40 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
26f50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
26f60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
26f70 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
26f80 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
26f90 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
26fa0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
26fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
26fc0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
26fd0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
26fe0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
26ff0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
27000 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
27010 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
27020 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
27030 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
27040 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
27050 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27060 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
27070 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
27080 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
27090 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
270a0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
270b0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
270c0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
270d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
270e0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
270f0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
27100 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
27110 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
27120 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27130 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
27140 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
27150 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
27160 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
27170 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
27180 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
27190 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
271a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
271b0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
271c0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
271d0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
271e0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
271f0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
27200 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
27210 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
27220 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
27230 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
27240 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
27250 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
27260 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
27270 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
27280 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
27290 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
272a0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
272b0 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
272c0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
272d0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
272e0 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
272f0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
27300 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
27310 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
27320 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
27330 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
27340 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
27350 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
27360 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
27370 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
27380 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
27390 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
273a0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
273b0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
273c0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
273d0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
273e0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
273f0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
27400 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
27410 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
27420 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
27430 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
27440 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
27450 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
27460 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
27470 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
27480 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
27490 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
274a0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
274b0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
274c0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
274d0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
274e0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
274f0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
27500 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
27510 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
27520 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
27530 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
27540 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
27550 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
27560 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
27570 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
27580 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
27590 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
275a0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
275b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
275c0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
275d0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
275e0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
275f0 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
27600 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
27610 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
27620 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
27630 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
27640 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
27650 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
27660 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
27670 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
27680 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
27690 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
276a0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
276b0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
276c0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
276d0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
276e0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
276f0 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
27700 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
27710 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
27720 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
27730 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
27740 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
27750 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
27760 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
27770 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
27780 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
27790 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
277a0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
277b0 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
277c0 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
277d0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
277e0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
277f0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27800 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
27810 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
27820 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
27830 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
27840 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
27850 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
27860 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
27870 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
27880 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
27890 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
278a0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
278b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
278c0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
278d0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
278e0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
278f0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
27900 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
27910 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
27920 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
27930 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
27940 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
27950 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
27960 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
27970 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
27980 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
27990 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
279a0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
279b0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
279c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
279d0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
279e0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
279f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
27a00 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
27a10 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
27a20 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
27a30 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
27a40 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
27a50 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
27a60 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
27a70 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
27a80 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
27a90 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
27aa0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
27ab0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
27ac0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
27ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
27ae0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
27af0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
27b00 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
27b10 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
27b20 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
27b30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27b40 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
27b50 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
27b60 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
27b70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
27b80 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
27b90 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
27ba0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
27bb0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
27bc0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
27bd0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
27be0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
27bf0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
27c00 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
27c10 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
27c20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
27c30 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
27c40 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
27c50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
27c60 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
27c70 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
27c80 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
27c90 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
27ca0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
27cb0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
27cc0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
27cd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
27ce0 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
27cf0 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54  ent SQL.**.** ^T
27d00 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
27d10 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
27d20 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
27d30 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
27d40 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
27d50 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
27d60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27d70 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
27d80 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
27d90 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
27da0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
27db0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
27dc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27dd0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  _v2()]..*/.const
27de0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
27df0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
27e00 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
27e10 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
27e20 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
27e30 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
27e40 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a  he Database.**.*
27e50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
27e60 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
27e70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27e80 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
27e90 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
27ea0 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
27eb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
27ec0 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
27ed0 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
27ee0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
27ef0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
27f00 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
27f10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27f20 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
27f30 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
27f40 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
27f50 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
27f60 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
27f70 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
27f80 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
27f90 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
27fa0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
27fb0 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
27fc0 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
27fd0 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
27fe0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
27ff0 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
28000 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
28010 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
28020 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
28030 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
28040 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
28050 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
28060 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
28070 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
28080 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
28090 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
280a0 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
280b0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
280c0 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
280d0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
280e0 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
280f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28100 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
28110 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
28120 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
28130 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
28140 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
28150 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
28160 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
28170 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
28180 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
28190 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
281a0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
281b0 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
281c0 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
281d0 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
281e0 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
281f0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
28200 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
28210 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
28220 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
28230 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
28240 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
28250 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
28260 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
28270 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
28280 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
28290 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
282a0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
282b0 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
282c0 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
282d0 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
282e0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
282f0 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
28300 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
28310 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
28320 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
28330 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
28340 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
28350 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71   disk..*/.int sq
28360 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
28370 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
28380 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
28390 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
283a0 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
283b0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
283c0 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a   Been Reset.**.*
283d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
283e0 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
283f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
28400 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
28410 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
28420 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
28430 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
28440 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
28450 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
28460 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
28470 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d  s not run to com
28480 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68  pletion and/or h
28490 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20  as not .** been 
284a0 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
284b0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
284c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
284d0 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
284e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
284f0 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
28500 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
28510 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
28520 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
28530 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
28540 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
28550 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28560 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
28570 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
28580 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
28590 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
285a0 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
285b0 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
285c0 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
285d0 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
285e0 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
285f0 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
28600 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28610 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
28620 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
28630 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
28640 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
28650 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
28660 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
28670 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
28680 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
28690 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
286a0 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
286b0 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
286c0 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
286d0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
286e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
286f0 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
28700 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
28710 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
28720 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
28730 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
28740 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
28750 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28760 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
28770 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
28780 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
28790 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
287a0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
287b0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
287c0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
287d0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
287e0 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
287f0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
28800 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
28810 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
28820 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
28830 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
28840 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
28850 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
28860 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
28870 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
28880 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
28890 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
288a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
288b0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
288c0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
288d0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
288e0 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
288f0 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
28900 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
28910 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
28920 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
28930 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
28940 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
28950 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28960 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
28970 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
28980 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
28990 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
289a0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
289b0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
289c0 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
289d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
289e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
289f0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
28a00 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
28a10 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
28a20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
28a30 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
28a40 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
28a50 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
28a60 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
28a70 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
28a80 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
28a90 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
28aa0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
28ab0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
28ac0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
28ad0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
28ae0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
28af0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
28b00 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
28b10 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
28b20 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
28b30 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
28b40 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
28b50 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
28b60 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
28b70 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
28b80 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
28b90 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
28ba0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
28bb0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
28bc0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
28bd0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
28be0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
28bf0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
28c00 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
28c10 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
28c20 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
28c30 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
28c40 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
28c50 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
28c60 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
28c70 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
28c80 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
28c90 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
28ca0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
28cb0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
28cc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28cd0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
28ce0 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
28cf0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
28d00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28d10 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
28d20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
28d30 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
28d40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28d50 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
28d60 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
28d70 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
28d80 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
28d90 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28da0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
28db0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
28dc0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
28dd0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
28de0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28df0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
28e00 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
28e10 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
28e20 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
28e30 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
28e40 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
28e50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
28e60 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
28e70 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
28e80 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
28e90 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
28ea0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
28eb0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
28ec0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
28ed0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
28ee0 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
28ef0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
28f00 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
28f10 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
28f20 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
28f30 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
28f40 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
28f50 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
28f60 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
28f70 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
28f80 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
28f90 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
28fa0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
28fb0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
28fc0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28fd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
28fe0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
28ff0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
29000 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
29010 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
29020 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
29030 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
29040 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
29050 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
29060 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
29070 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
29080 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
29090 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
290a0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
290b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
290c0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
290d0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
290e0 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
290f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
29100 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
29110 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
29120 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
29130 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
29140 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
29150 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
29160 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
29170 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
29180 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
29190 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
291a0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
291b0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
291c0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
291d0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
291e0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
291f0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
29200 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
29210 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
29220 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
29230 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
29240 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
29250 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
29260 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
29270 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
29280 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
29290 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
292a0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
292b0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
292c0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
292d0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
292e0 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
292f0 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
29300 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
29310 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
29320 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
29330 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
29340 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
29350 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
29360 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
29370 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
29380 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
29390 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
293a0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
293b0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
293c0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
293d0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
293e0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
293f0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
29400 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
29410 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
29420 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
29430 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
29440 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
29450 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
29460 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
29470 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
29480 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
29490 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
294a0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
294b0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
294c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
294d0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
294e0 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
294f0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
29500 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
29510 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
29520 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
29530 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
29540 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
29550 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
29560 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
29570 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
29580 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
29590 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
295a0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
295b0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
295c0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
295d0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
295e0 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
295f0 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
29600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29610 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
29620 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
29630 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
29640 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
29650 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
29660 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
29670 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
29680 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
29690 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
296a0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
296b0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
296c0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
296d0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
296e0 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
296f0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
29700 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
29710 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
29720 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
29730 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
29740 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29750 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
29760 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
29770 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
29780 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
29790 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
297a0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
297b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
297c0 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
297d0 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
297e0 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
297f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
29800 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
29810 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
29820 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
29830 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
29840 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
29850 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
29860 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
29870 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
29880 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
29890 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
298a0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
298b0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
298c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
298d0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
298e0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
298f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
29900 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
29910 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29920 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
29930 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
29940 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
29950 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
29960 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
29970 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
29980 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
29990 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
299a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
299b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
299c0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
299d0 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
299e0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
299f0 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
29a00 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
29a10 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
29a20 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
29a30 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
29a40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29a50 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33  t16() or sqlite3
29a60 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74  _bind_text64() t
29a70 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61  hen.** that para
29a80 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
29a90 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
29aa0 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
29ab0 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
29ac0 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
29ad0 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
29ae0 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
29af0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
29b00 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
29b10 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
29b20 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
29b30 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
29b40 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
29b50 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
29b60 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
29b70 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
29b80 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
29b90 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
29ba0 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
29bb0 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
29bc0 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
29bd0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
29be0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
29bf0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
29c00 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20  BLOB and string 
29c10 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63  binding interfac
29c20 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72  es.** is a destr
29c30 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
29c40 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
29c50 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
29c60 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
29c70 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
29c80 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
29c90 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
29ca0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
29cb0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
29cc0 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
29cd0 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61  l to bind API fa
29ce0 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ils..** ^If the 
29cf0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
29d00 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
29d10 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
29d20 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
29d30 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
29d40 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
29d50 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
29d60 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
29d70 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
29d80 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
29d90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
29da0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
29db0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
29dc0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
29dd0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
29de0 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
29df0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
29e00 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
29e10 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
29e20 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
29e30 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
29e40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
29e50 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
29e60 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
29e70 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f  () must be one o
29e80 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  f.** [SQLITE_UTF
29e90 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
29ea0 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  6], [SQLITE_UTF1
29eb0 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
29ec0 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20  _UTF16LE].** to 
29ed0 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f  specify the enco
29ee0 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74  ding of the text
29ef0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
29f00 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20  rameter.  If.** 
29f10 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  the sixth argume
29f20 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
29f30 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e  nd_text64() is n
29f40 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
29f50 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20   allowed values 
29f60 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20  shown above, or 
29f70 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  if the text enco
29f80 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
29f90 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e  t.** from the en
29fa0 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
29fb0 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61   by the sixth pa
29fc0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
29fd0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73  e behavior.** is
29fe0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
29ff0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2a000 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
2a010 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
2a020 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
2a030 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
2a040 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
2a050 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
2a060 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
2a070 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
2a080 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
2a090 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
2a0a0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
2a0b0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
2a0c0 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
2a0d0 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
2a0e0 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
2a0f0 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
2a100 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
2a110 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
2a120 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
2a130 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
2a140 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
2a150 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
2a160 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
2a170 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
2a180 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
2a190 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
2a1a0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
2a1b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2a1c0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
2a1d0 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
2a1e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2a1f0 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
2a200 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
2a210 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
2a220 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
2a230 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
2a240 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
2a250 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
2a260 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
2a270 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
2a280 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
2a290 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
2a2a0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
2a2b0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
2a2c0 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
2a2d0 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
2a2e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a2f0 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
2a300 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
2a310 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2a320 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
2a330 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
2a340 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
2a350 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
2a360 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a370 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
2a380 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
2a390 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
2a3a0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
2a3b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
2a3c0 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
2a3d0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
2a3e0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
2a3f0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
2a400 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
2a410 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
2a420 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d  SQLITE_TOOBIG] m
2a430 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2a440 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20   if the size of 
2a450 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2a460 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69  .** exceeds limi
2a470 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73  ts imposed by [s
2a480 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2a490 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2a4a0 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  TH]) or.** [SQLI
2a4b0 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a  TE_MAX_LENGTH]..
2a4c0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
2a4d0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
2a4e0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
2a4f0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
2a500 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
2a510 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
2a520 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
2a530 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
2a540 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2a550 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a560 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
2a570 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a580 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2a590 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2a5a0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2a5b0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
2a5c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
2a5d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a5e0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2a5f0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
2a600 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2a610 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28  te3_bind_blob64(
2a620 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a630 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2a640 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2a650 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2a660 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
2a670 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2a680 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
2a690 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a6a0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
2a6b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2a6c0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2a6d0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
2a6e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2a6f0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2a700 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2a710 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
2a720 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
2a730 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a740 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
2a750 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
2a760 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73  3_stmt*,int,cons
2a770 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64  t char*,int,void
2a780 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2a790 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a7a0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2a7b0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2a7c0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2a7d0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2a7e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2a7f0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2a800 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
2a810 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  ar*, sqlite3_uin
2a820 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2a830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2a840 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
2a850 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
2a860 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ding);.int sqlit
2a870 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
2a880 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a890 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
2a8a0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2a8b0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2a8c0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2a8d0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
2a8e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a8f0 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
2a900 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
2a910 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2a920 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2a930 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2a940 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2a950 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2a960 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2a970 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2a980 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
2a990 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
2a9a0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
2a9b0 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
2a9c0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
2a9d0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2a9e0 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
2a9f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2aa00 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
2aa10 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2aa20 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
2aa30 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
2aa40 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
2aa50 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
2aa60 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
2aa70 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
2aa80 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
2aa90 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
2aaa0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
2aab0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
2aac0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2aad0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
2aae0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
2aaf0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
2ab00 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
2ab10 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
2ab20 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
2ab30 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2ab40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ab50 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2ab60 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2ab70 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ab80 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
2ab90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2aba0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2abb0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2abc0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2abd0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2abe0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2abf0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2ac00 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2ac10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ac20 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ac30 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
2ac40 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
2ac50 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2ac60 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
2ac70 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
2ac80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ac90 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
2aca0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2acb0 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
2acc0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2acd0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
2ace0 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
2acf0 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
2ad00 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2ad10 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2ad20 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
2ad30 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
2ad40 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
2ad50 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
2ad60 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
2ad70 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
2ad80 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
2ad90 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
2ada0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
2adb0 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
2adc0 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
2add0 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
2ade0 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
2adf0 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
2ae00 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
2ae10 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
2ae20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
2ae30 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
2ae40 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
2ae50 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
2ae60 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
2ae70 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
2ae80 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
2ae90 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
2aea0 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
2aeb0 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
2aec0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2aed0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
2aee0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
2aef0 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
2af00 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
2af10 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
2af20 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
2af30 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
2af40 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
2af50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2af60 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2af70 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2af80 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2af90 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2afa0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2afb0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2afc0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2afd0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2afe0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
2aff0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2b000 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2b010 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2b020 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
2b030 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
2b040 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
2b050 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
2b060 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  me.**.** ^Return
2b070 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
2b080 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
2b090 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
2b0a0 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
2b0b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
2b0c0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
2b0d0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
2b0e0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
2b0f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2b100 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2b110 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
2b120 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
2b130 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
2b140 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
2b150 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
2b160 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
2b170 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
2b180 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
2b190 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
2b1a0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
2b1b0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
2b1c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
2b1d0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2b1e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2b1f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2b200 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2b210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2b220 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2b230 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2b240 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2b250 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2b260 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
2b270 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2b280 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
2b290 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2b2a0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
2b2b0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
2b2c0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
2b2d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2b2e0 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
2b2f0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
2b300 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
2b310 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
2b320 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
2b330 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2b340 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
2b350 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
2b360 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2b370 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
2b380 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
2b390 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2b3a0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
2b3b0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2b3c0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2b3d0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2b3e0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2b3f0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
2b400 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
2b410 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
2b420 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2b430 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2b440 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2b450 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2b460 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
2b470 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2b480 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
2b490 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
2b4a0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
2b4b0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
2b4c0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
2b4d0 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
2b4e0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
2b4f0 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
2b500 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2b510 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
2b520 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2b530 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b540 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
2b550 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
2b560 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2b570 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
2b580 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
2b590 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
2b5a0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
2b5b0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2b5c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2b5d0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
2b5e0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
2b5f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b600 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2b610 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2b620 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
2b630 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2b640 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
2b650 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2b660 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2b670 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
2b680 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
2b690 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2b6a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b6b0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
2b6c0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
2b6d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2b6e0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
2b6f0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
2b700 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
2b710 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
2b720 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
2b730 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
2b740 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2b750 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
2b760 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
2b770 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b780 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
2b790 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
2b7a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2b7b0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2b7c0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2b7d0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2b7e0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2b7f0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2b800 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2b810 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2b820 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2b830 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
2b840 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2b850 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
2b860 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
2b870 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
2b880 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
2b890 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
2b8a0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
2b8b0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
2b8c0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
2b8d0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
2b8e0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
2b8f0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
2b900 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
2b910 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
2b920 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2b930 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
2b940 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2b950 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2b960 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
2b970 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
2b980 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
2b990 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
2b9a0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
2b9b0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
2b9c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
2b9d0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
2b9e0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
2b9f0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
2ba00 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
2ba10 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
2ba20 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2ba30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2ba40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ba50 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
2ba60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2ba70 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
2ba80 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2ba90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2baa0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
2bab0 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
2bac0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ult.**.** ^These
2bad0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
2bae0 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
2baf0 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
2bb00 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
2bb10 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
2bb20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
2bb30 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
2bb40 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
2bb50 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
2bb60 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
2bb70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
2bb80 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
2bb90 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
2bba0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
2bbb0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
2bbc0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2bbd0 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
2bbe0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2bbf0 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
2bc00 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
2bc10 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
2bc20 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
2bc30 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
2bc40 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
2bc50 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
2bc60 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
2bc70 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2bc80 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2bc90 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2bca0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
2bcb0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
2bcc0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2bcd0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2bce0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2bcf0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2bd00 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2bd10 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2bd20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2bd30 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2bd40 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2bd50 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
2bd60 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
2bd70 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
2bd80 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
2bd90 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
2bda0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
2bdb0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
2bdc0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
2bdd0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
2bde0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
2bdf0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
2be00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2be10 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
2be20 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
2be30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2be40 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2be50 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
2be60 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
2be70 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
2be80 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
2be90 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
2bea0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2beb0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
2bec0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
2bed0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
2bee0 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
2bef0 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
2bf00 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
2bf10 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
2bf20 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
2bf30 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
2bf40 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
2bf50 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
2bf60 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
2bf70 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
2bf80 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2bf90 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
2bfa0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
2bfb0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
2bfc0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
2bfd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2bfe0 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
2bff0 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
2c000 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
2c010 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
2c020 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
2c030 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
2c040 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
2c050 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
2c060 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
2c070 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
2c080 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
2c090 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
2c0a0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
2c0b0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
2c0c0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
2c0d0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
2c0e0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2c0f0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
2c100 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
2c110 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2c120 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2c130 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2c140 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2c150 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2c160 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2c170 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
2c180 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2c190 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2c1a0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
2c1b0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
2c1c0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
2c1d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c1e0 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
2c1f0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2c200 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2c210 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
2c220 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2c230 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2c240 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
2c250 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c260 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
2c270 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
2c280 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
2c290 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
2c2a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c2b0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
2c2c0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
2c2d0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2c2e0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2c2f0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
2c300 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2c310 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2c320 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2c330 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2c340 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2c350 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2c360 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2c370 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
2c380 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2c390 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
2c3a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2c3b0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2c3c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2c3d0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
2c3e0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2c3f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2c400 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2c410 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2c420 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2c430 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2c440 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
2c450 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2c460 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2c470 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
2c480 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
2c490 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
2c4a0 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
2c4b0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
2c4c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c4d0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
2c4e0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
2c4f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
2c500 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
2c510 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
2c520 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
2c530 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
2c540 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
2c550 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
2c560 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2c570 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
2c580 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
2c590 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
2c5a0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
2c5b0 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
2c5c0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
2c5d0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
2c5e0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2c5f0 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
2c600 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2c610 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
2c620 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2c630 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
2c640 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
2c650 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2c660 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
2c670 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
2c680 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
2c690 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
2c6a0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
2c6b0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
2c6c0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
2c6d0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
2c6e0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
2c6f0 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
2c700 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
2c710 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
2c720 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
2c730 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
2c740 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
2c750 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
2c760 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
2c770 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
2c780 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
2c790 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
2c7a0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
2c7b0 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
2c7c0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
2c7d0 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
2c7e0 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
2c7f0 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
2c800 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
2c810 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
2c820 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
2c830 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
2c840 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
2c850 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
2c860 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
2c870 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
2c880 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
2c890 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
2c8a0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
2c8b0 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
2c8c0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
2c8d0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
2c8e0 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
2c8f0 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
2c900 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c910 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
2c920 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2c930 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c940 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2c950 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2c960 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2c970 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
2c980 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
2c990 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
2c9a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c9b0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
2c9c0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
2c9d0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2c9e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2c9f0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2ca00 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
2ca10 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
2ca20 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
2ca30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2ca40 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2ca50 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
2ca60 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
2ca70 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
2ca80 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
2ca90 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
2caa0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
2cab0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
2cac0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
2cad0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2cae0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
2caf0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
2cb00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
2cb10 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
2cb20 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
2cb30 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
2cb40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2cb50 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2cb60 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2cb70 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
2cb80 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2cb90 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2cba0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2cbb0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
2cbc0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2cbd0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
2cbe0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2cbf0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
2cc00 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
2cc10 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2cc20 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
2cc30 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
2cc40 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
2cc50 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2cc60 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
2cc70 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
2cc80 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
2cc90 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
2cca0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
2ccb0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
2ccc0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
2ccd0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
2cce0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2ccf0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
2cd00 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
2cd10 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
2cd20 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2cd30 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
2cd40 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
2cd50 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
2cd60 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
2cd70 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
2cd80 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
2cd90 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
2cda0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
2cdb0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
2cdc0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
2cdd0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2cde0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
2cdf0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
2ce00 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
2ce10 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
2ce20 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
2ce30 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
2ce40 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2ce50 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
2ce60 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
2ce70 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
2ce80 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
2ce90 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
2cea0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
2ceb0 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
2cec0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
2ced0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
2cee0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2cef0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
2cf00 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
2cf10 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
2cf20 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
2cf30 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2cf40 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2cf50 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
2cf60 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
2cf70 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
2cf80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2cf90 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
2cfa0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2cfb0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
2cfc0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
2cfd0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
2cfe0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
2cff0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
2d000 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
2d010 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
2d020 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
2d030 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
2d040 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
2d050 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
2d060 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
2d070 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
2d080 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
2d090 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
2d0a0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
2d0b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2d0c0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
2d0d0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
2d0e0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
2d0f0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
2d100 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
2d110 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
2d120 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
2d130 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
2d140 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
2d150 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
2d160 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2d170 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2d180 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
2d190 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
2d1a0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
2d1b0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2d1c0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
2d1d0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
2d1e0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
2d1f0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2d200 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
2d210 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
2d220 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
2d230 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
2d240 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
2d250 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
2d260 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
2d270 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2d280 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2d290 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
2d2a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2d2b0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
2d2c0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
2d2d0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2d2e0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
2d2f0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
2d300 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
2d310 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
2d320 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
2d330 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
2d340 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
2d350 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
2d360 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
2d370 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
2d380 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d390 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
2d3a0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
2d3b0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2d3c0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
2d3d0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
2d3e0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
2d3f0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
2d400 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2d410 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
2d420 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
2d430 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
2d440 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d450 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
2d460 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
2d470 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
2d480 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
2d490 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
2d4a0 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
2d4b0 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
2d4c0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
2d4d0 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
2d4e0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2d4f0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
2d500 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
2d510 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
2d520 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
2d530 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2d540 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
2d550 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
2d560 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
2d570 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
2d580 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
2d590 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d5a0 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
2d5b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2d5c0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
2d5d0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2d5e0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
2d5f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2d600 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
2d610 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
2d620 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
2d630 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
2d640 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d650 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2d660 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
2d670 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
2d680 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
2d690 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
2d6a0 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
2d6b0 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
2d6c0 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
2d6d0 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
2d6e0 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
2d6f0 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
2d700 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
2d710 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
2d720 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
2d730 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
2d740 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
2d750 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
2d760 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
2d770 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
2d780 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
2d790 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
2d7a0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
2d7b0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2d7c0 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
2d7d0 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
2d7e0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
2d7f0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
2d800 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
2d810 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
2d820 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
2d830 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2d840 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
2d850 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
2d860 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
2d870 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d880 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2d890 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
2d8a0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
2d8b0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
2d8c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
2d8d0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
2d8e0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
2d8f0 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
2d900 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
2d910 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
2d920 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
2d930 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
2d940 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
2d950 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
2d960 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
2d970 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
2d980 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
2d990 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2d9a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2d9b0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
2d9c0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
2d9d0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
2d9e0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
2d9f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2da00 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
2da10 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
2da20 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
2da30 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
2da40 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
2da50 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
2da60 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
2da70 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
2da80 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2da90 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
2daa0 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
2dab0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2dac0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2dad0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2dae0 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
2daf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2db00 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
2db10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2db20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2db30 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
2db40 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2db50 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2db60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2db70 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
2db80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2db90 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
2dba0 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
2dbb0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
2dbc0 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
2dbd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2dbe0 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
2dbf0 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
2dc00 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
2dc10 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2dc20 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
2dc30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2dc40 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2dc50 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
2dc60 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
2dc70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2dc80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2dc90 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2dca0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2dcb0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2dcc0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2dcd0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2dce0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
2dcf0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2dd00 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
2dd10 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
2dd20 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
2dd30 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
2dd40 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2dd50 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2dd60 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
2dd70 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
2dd80 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
2dd90 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
2dda0 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
2ddb0 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
2ddc0 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
2ddd0 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
2dde0 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
2ddf0 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
2de00 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
2de10 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
2de20 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
2de30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
2de40 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
2de50 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2de60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2de70 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
2de80 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
2de90 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
2dea0 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
2deb0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
2dec0 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
2ded0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
2dee0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2def0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
2df00 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
2df10 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
2df20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2df30 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
2df40 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
2df50 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
2df60 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
2df70 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2df80 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
2df90 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
2dfa0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2dfb0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
2dfc0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
2dfd0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
2dfe0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
2dff0 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
2e000 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
2e010 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
2e020 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
2e030 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
2e040 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
2e050 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
2e060 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
2e070 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
2e080 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
2e090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2e0a0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
2e0b0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
2e0c0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2e0d0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
2e0e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
2e0f0 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
2e100 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
2e110 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2e120 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
2e130 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
2e140 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
2e150 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
2e160 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
2e170 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
2e180 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
2e190 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
2e1a0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2e1b0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
2e1c0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
2e1d0 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
2e1e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2e1f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2e200 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2e210 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
2e220 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
2e230 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
2e240 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
2e250 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
2e260 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
2e270 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2e280 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
2e290 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e2a0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
2e2b0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
2e2c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
2e2d0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
2e2e0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2e2f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2e300 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
2e310 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
2e320 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2e330 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2e340 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
2e350 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
2e360 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
2e370 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
2e380 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2e390 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2e3a0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
2e3b0 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
2e3c0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2e3d0 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
2e3e0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
2e3f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
2e400 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
2e410 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2e420 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2e430 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
2e440 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
2e450 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
2e460 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
2e470 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
2e480 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
2e490 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
2e4a0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
2e4b0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2e4c0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
2e4d0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2e4e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2e4f0 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
2e500 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
2e510 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2e520 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
2e530 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2e540 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
2e550 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
2e560 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
2e570 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2e580 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
2e590 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e5a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2e5b0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
2e5c0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
2e5d0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2e5e0 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
2e5f0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2e600 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
2e610 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2e620 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
2e630 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2e640 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
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 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
2e670 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
2e680 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
2e690 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
2e6a0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2e6b0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
2e6c0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2e6d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2e6e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2e6f0 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
2e700 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2e710 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2e720 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
2e730 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
2e740 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
2e750 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
2e760 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
2e770 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
2e780 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
2e790 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
2e7a0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
2e7b0 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
2e7c0 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
2e7d0 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
2e7e0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
2e7f0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2e800 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
2e810 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
2e820 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
2e830 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
2e840 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
2e850 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
2e860 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2e870 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
2e880 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2e890 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2e8a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
2e8b0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
2e8c0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
2e8d0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
2e8e0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
2e8f0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
2e900 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
2e910 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
2e920 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e930 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2e940 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
2e950 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2e960 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
2e970 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2e980 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2e990 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2e9a0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2e9b0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2e9c0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2e9d0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2e9e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
2e9f0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2ea00 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
2ea10 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2ea20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2ea30 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2ea40 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2ea50 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2ea60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ea70 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
2ea80 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2ea90 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2eaa0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2eab0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
2eac0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2ead0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2eae0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2eaf0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2eb00 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2eb10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2eb20 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
2eb30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2eb40 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2eb50 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2eb60 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2eb70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2eb80 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
2eb90 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2eba0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2ebb0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2ebc0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2ebd0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
2ebe0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2ebf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ec00 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
2ec10 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2ec20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
2ec30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2ec40 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2ec50 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2ec60 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2ec70 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2ec80 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2ec90 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2eca0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2ecb0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2ecc0 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
2ecd0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2ece0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2ecf0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2ed00 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2ed10 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2ed20 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2ed30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ed40 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2ed50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
2ed60 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
2ed70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ed80 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
2ed90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2eda0 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
2edb0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
2edc0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
2edd0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
2ede0 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
2edf0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
2ee00 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2ee10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2ee20 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2ee30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ee40 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
2ee50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
2ee60 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
2ee70 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
2ee80 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2ee90 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
2eea0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
2eeb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2eec0 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
2eed0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2eee0 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
2eef0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
2ef00 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
2ef10 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
2ef20 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
2ef30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ef40 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
2ef50 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
2ef60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2ef70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
2ef80 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
2ef90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2efa0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
2efb0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2efc0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2efd0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
2efe0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2eff0 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
2f000 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2f010 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
2f020 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2f030 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2f040 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
2f050 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2f060 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f070 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2f080 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2f090 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2f0a0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
2f0b0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
2f0c0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
2f0d0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2f0e0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
2f0f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f100 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2f110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2f120 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
2f130 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2f140 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
2f150 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
2f160 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
2f170 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
2f180 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
2f190 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
2f1a0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
2f1b0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
2f1c0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
2f1d0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
2f1e0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
2f1f0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
2f200 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
2f210 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
2f220 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
2f230 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
2f240 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
2f250 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
2f260 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
2f270 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
2f280 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2f290 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2f2a0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2f2b0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
2f2c0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
2f2d0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
2f2e0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
2f2f0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
2f300 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
2f310 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
2f320 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
2f330 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2f340 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2f350 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
2f360 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2f370 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2f380 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2f390 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2f3a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2f3b0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
2f3c0 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
2f3d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2f3e0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2f3f0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
2f400 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2f410 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
2f420 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
2f430 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2f440 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2f450 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2f460 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
2f470 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2f480 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
2f490 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2f4a0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
2f4b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2f4c0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
2f4d0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
2f4e0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
2f4f0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2f500 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2f510 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2f520 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2f530 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2f540 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2f550 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
2f560 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
2f570 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2f580 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2f590 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
2f5a0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
2f5b0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2f5c0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
2f5d0 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
2f5e0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2f5f0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2f600 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
2f610 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2f620 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
2f630 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
2f640 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
2f650 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2f660 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2f670 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
2f680 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
2f690 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
2f6a0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
2f6b0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
2f6c0 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
2f6d0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2f6e0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
2f6f0 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
2f700 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
2f710 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
2f720 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
2f730 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
2f740 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
2f750 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
2f760 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
2f770 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
2f780 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
2f790 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
2f7a0 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
2f7b0 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
2f7c0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
2f7d0 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
2f7e0 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
2f7f0 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
2f800 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
2f810 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
2f820 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
2f830 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
2f840 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
2f850 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
2f860 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
2f870 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2f880 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
2f890 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2f8a0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
2f8b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2f8c0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
2f8d0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
2f8e0 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
2f8f0 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
2f900 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
2f910 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
2f920 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
2f930 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
2f940 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2f950 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
2f960 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f970 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
2f980 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2f990 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2f9a0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
2f9b0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
2f9c0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
2f9d0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
2f9e0 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
2f9f0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2fa00 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
2fa10 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2fa20 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2fa30 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2fa40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2fa50 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2fa60 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2fa70 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2fa80 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
2fa90 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2faa0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2fab0 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
2fac0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2fad0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2fae0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2faf0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
2fb00 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2fb10 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2fb20 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2fb30 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
2fb40 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
2fb50 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
2fb60 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
2fb70 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
2fb80 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
2fb90 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
2fba0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
2fbb0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
2fbc0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
2fbd0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2fbe0 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
2fbf0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
2fc00 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
2fc10 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
2fc20 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
2fc30 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
2fc40 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
2fc50 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
2fc60 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
2fc70 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
2fc80 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
2fc90 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
2fca0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
2fcb0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
2fcc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
2fcd0 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
2fce0 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
2fcf0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
2fd00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2fd10 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
2fd20 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
2fd30 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
2fd40 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2fd50 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
2fd60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2fd70 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2fd80 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2fd90 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2fda0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2fdb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fdc0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
2fdd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fde0 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
2fdf0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2fe00 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
2fe10 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2fe20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2fe30 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
2fe40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fe50 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
2fe60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2fe70 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
2fe80 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
2fe90 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
2fea0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
2feb0 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
2fec0 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
2fed0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2fee0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
2fef0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ff00 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
2ff10 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
2ff20 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
2ff30 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
2ff40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2ff50 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2ff60 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
2ff70 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2ff80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ff90 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
2ffa0 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
2ffb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ffc0 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
2ffd0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2ffe0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
2fff0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
30000 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
30010 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
30020 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
30030 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
30040 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
30050 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
30060 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
30070 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
30080 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
30090 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
300a0 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
300b0 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
300c0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
300d0 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
300e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
300f0 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
30100 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
30110 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
30120 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
30130 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
30140 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30150 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
30160 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
30170 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
30180 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
30190 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
301a0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
301b0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
301c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
301d0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
301e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
301f0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
30200 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
30210 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
30220 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
30230 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
30240 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
30250 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
30260 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
30270 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
30280 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
30290 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63  E_NOMEM].)^.*/.c
302a0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
302b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
302c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
302d0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
302e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
302f0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
30300 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
30310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30320 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
30330 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30340 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
30350 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
30360 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30370 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
30380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
30390 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
303a0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
303b0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
303c0 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
303d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
303e0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
303f0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
30400 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
30410 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30420 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
30430 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
30440 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
30450 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
30460 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
30470 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
30480 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30490 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
304a0 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
304b0 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
304c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
304d0 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
304e0 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
304f0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
30500 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
30510 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
30520 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
30530 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
30540 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
30550 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
30560 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
30570 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
30580 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
30590 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
305a0 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
305b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
305c0 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
305d0 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
305e0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
305f0 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
30600 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
30610 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
30620 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
30630 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
30640 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
30650 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
30660 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
30670 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
30680 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
30690 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
306a0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
306b0 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
306c0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
306d0 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
306e0 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
306f0 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
30700 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
30710 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
30720 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
30730 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
30740 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
30750 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
30760 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
30770 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
30780 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
30790 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
307a0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
307b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
307c0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
307d0 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
307e0 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
307f0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
30800 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
30810 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
30820 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
30830 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
30840 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
30850 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30860 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
30870 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
30880 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
30890 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
308a0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
308b0 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
308c0 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
308d0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
308e0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
308f0 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
30900 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
30910 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
30920 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
30930 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
30940 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
30950 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
30960 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
30970 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
30980 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
30990 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
309a0 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
309b0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
309c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
309d0 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
309e0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
309f0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
30a00 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
30a10 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
30a20 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
30a30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
30a40 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
30a50 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
30a60 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
30a70 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
30a80 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
30a90 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
30aa0 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
30ab0 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
30ac0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
30ad0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
30ae0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
30af0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
30b00 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
30b10 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
30b20 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
30b30 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
30b40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
30b50 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
30b60 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
30b70 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
30b80 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
30b90 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
30ba0 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
30bb0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
30bc0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
30bd0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
30be0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
30bf0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
30c00 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
30c10 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
30c20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
30c30 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
30c40 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
30c50 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
30c60 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
30c70 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
30c80 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
30c90 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
30ca0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
30cb0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
30cc0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
30cd0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
30ce0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30cf0 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
30d00 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
30d10 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
30d20 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
30d30 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
30d40 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
30d50 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
30d60 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
30d70 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
30d80 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
30d90 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
30da0 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
30db0 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
30dc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30dd0 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
30de0 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
30df0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
30e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
30e10 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
30e20 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
30e30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
30e40 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
30e50 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
30e60 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
30e70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
30e80 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
30e90 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
30ea0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
30eb0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
30ec0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
30ed0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
30ee0 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
30ef0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
30f00 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
30f10 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
30f20 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
30f30 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
30f40 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
30f50 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
30f60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
30f70 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
30f80 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
30f90 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
30fa0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
30fb0 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
30fc0 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
30fd0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
30fe0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
30ff0 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
31000 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
31010 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
31020 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
31030 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
31040 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
31050 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31060 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
31070 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
31080 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
31090 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
310a0 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
310b0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
310c0 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
310d0 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
310e0 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
310f0 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
31100 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
31110 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
31120 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
31130 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
31140 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
31150 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
31160 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
31170 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
31180 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
31190 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
311a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
311b0 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
311c0 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
311d0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
311e0 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
311f0 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
31200 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
31210 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
31220 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
31230 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
31240 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
31250 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
31260 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
31270 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
31280 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
31290 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
312a0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
312b0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
312c0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
312d0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
312e0 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
312f0 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
31300 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
31310 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
31320 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
31330 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
31340 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
31350 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
31360 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
31370 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
31380 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
31390 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
313a0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
313b0 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
313c0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
313d0 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
313e0 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
313f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
31400 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
31410 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
31420 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
31430 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
31440 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
31450 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
31460 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
31470 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
31480 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
31490 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
314a0 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
314b0 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
314c0 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
314d0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
314e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
314f0 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
31500 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20  arameters.  The 
31510 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
31520 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61  ld set this para
31530 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c  meter to.** [SQL
31540 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20  ITE_UTF16LE] if 
31550 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
31560 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
31570 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  kes .** [sqlite3
31580 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
31590 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20  )] on an input, 
315a0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
315b0 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d  BE] if the.** im
315c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
315d0 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61  okes [sqlite3_va
315e0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20  lue_text16be()] 
315f0 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a  on an input, or.
31600 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
31610 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  ] if [sqlite3_va
31620 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73  lue_text16()] is
31630 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54   used, or [SQLIT
31640 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72  E_UTF8].** other
31650 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65  wise.  ^The same
31660 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61   SQL function ma
31670 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
31680 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
31690 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e  sing.** differen
316a0 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  t preferred text
316b0 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68   encodings, with
316c0 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65   different imple
316d0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a  mentations for.*
316e0 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e  * each encoding.
316f0 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
31700 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
31710 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
31720 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
31730 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
31740 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
31750 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
31760 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
31770 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
31780 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sion..**.** ^The
31790 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
317a0 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79  r may optionally
317b0 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53   be ORed with [S
317c0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
317d0 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  TIC].** to signa
317e0 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74  l that the funct
317f0 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ion will always 
31800 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
31810 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20  result given.** 
31820 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20  the same inputs 
31830 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20  within a single 
31840 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
31850 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  Most SQL functio
31860 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d  ns are.** determ
31870 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75  inistic.  The bu
31880 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29  ilt-in [random()
31890 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  ] SQL function i
318a0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
318b0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  a.** function th
318c0 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d  at is not determ
318d0 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51  inistic.  The SQ
318e0 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e  Lite query plann
318f0 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a  er is able to.**
31900 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f   perform additio
31910 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  nal optimization
31920 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74  s on determinist
31930 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f  ic functions, so
31940 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b   use.** of the [
31950 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
31960 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65  STIC] flag is re
31970 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20  commended where 
31980 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  possible..**.** 
31990 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
319a0 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
319b0 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
319c0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
319d0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
319e0 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
319f0 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
31a00 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
31a10 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
31a20 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ].)^.**.** ^The 
31a30 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61  sixth, seventh a
31a40 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65  nd eighth parame
31a50 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
31a60 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
31a70 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
31a80 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
31a90 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
31aa0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
31ab0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
31ac0 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
31ad0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
31ae0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
31af0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
31b00 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
31b10 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
31b20 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70  inters must be p
31b30 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
31b40 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
31b50 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
31b60 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
31b70 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
31b80 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
31b90 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
31ba0 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
31bb0 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20  LL pointer must 
31bc0 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
31bd0 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20  unc. ^To delete 
31be0 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
31bf0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
31c00 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
31c10 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72  ULL pointers for
31c20 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
31c30 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73  ion.** callbacks
31c40 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65  ..**.** ^(If the
31c50 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
31c60 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
31c70 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
31c80 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
31c90 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74   then it is dest
31ca0 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61  ructor for the a
31cb0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
31cc0 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65  pointer. .** The
31cd0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69   destructor is i
31ce0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
31cf0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
31d00 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62  ted, either by b
31d10 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64  eing.** overload
31d20 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64  ed or when the d
31d30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31d40 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20  on closes.)^.** 
31d50 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
31d60 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20  is also invoked 
31d70 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  if the call to.*
31d80 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
31d90 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66  _function_v2() f
31da0 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74  ails..** ^When t
31db0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61  he destructor ca
31dc0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65  llback of the te
31dd0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  nth parameter is
31de0 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20   invoked, it.** 
31df0 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67  is passed a sing
31e00 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
31e10 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  h is a copy of t
31e20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
31e30 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ata .** pointer 
31e40 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69  which was the fi
31e50 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  fth parameter to
31e60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31e70 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  function_v2()..*
31e80 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d  *.** ^It is perm
31e90 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
31ea0 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
31eb0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
31ec0 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
31ed0 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
31ee0 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
31ef0 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
31f00 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
31f10 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
31f20 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
31f30 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
31f40 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
31f50 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
31f60 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
31f70 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
31f80 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
31f90 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
31fa0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
31fb0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70   ^A function imp
31fc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
31fd0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
31fe0 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
31ff0 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
32000 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
32010 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
32020 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
32030 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20  ative nArg.  ^A 
32040 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
32050 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
32060 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
32070 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
32080 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
32090 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
320a0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
320b0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
320c0 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
320d0 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69  .  .** ^A functi
320e0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
320f0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
32100 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
32110 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
32120 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
32130 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
32140 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
32150 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
32160 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
32170 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
32180 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e  .**.** ^Built-in
32190 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
321a0 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20  e overloaded by 
321b0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  new application-
321c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
321d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70  s..**.** ^An app
321e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
321f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
32200 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
32210 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
32220 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
32230 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
32240 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
32250 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
32260 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
32270 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
32280 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
32290 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
322a0 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
322b0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69  is running..*/.i
322c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
322d0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
322e0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
322f0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
32300 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
32310 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
32320 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
32330 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
32340 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32350 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
32360 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
32370 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
32380 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
32390 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
323a0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
323b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
323c0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
323d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
323e0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
323f0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
32400 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
32410 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
32420 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
32430 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
32440 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
32450 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
32460 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
32470 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
32480 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32490 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
324a0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
324b0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
324c0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
324d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
324e0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
324f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
32500 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
32510 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
32520 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
32530 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
32540 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
32550 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
32560 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
32570 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
32580 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
32590 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
325a0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
325b0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
325c0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
325d0 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  ext*),.  void(*x
325e0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
325f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32600 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
32610 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
32620 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
32630 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
32640 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
32650 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
32660 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
32670 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
32680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
32690 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
326a0 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33  1    /* IMP: R-3
326b0 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64  7514-35566 */.#d
326c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
326d0 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20  16LE        2   
326e0 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31   /* IMP: R-03371
326f0 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e  -37637 */.#defin
32700 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
32710 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20          3    /* 
32720 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31  IMP: R-51971-341
32730 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  54 */.#define SQ
32740 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
32750 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
32760 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
32770 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
32780 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
32790 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65     5    /* Depre
327a0 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  cated */.#define
327b0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
327c0 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
327d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
327e0 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
327f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32800 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a   Function Flags.
32810 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
32820 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65  tants may be ORe
32830 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20  d together with 
32840 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
32850 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64  UTF8 | preferred
32860 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
32870 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
32880 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
32890 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
328a0 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ction()], [sqlit
328b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
328c0 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
328d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
328e0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  unction_v2()]..*
328f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
32900 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20  _DETERMINISTIC  
32910 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43    0x800../*.** C
32920 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
32930 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
32940 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
32950 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
32960 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
32970 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
32980 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
32990 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
329a0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
329b0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
329c0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
329d0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
329e0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
329f0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
32a00 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
32a10 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
32a20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
32a30 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
32a40 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
32a50 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
32a60 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
32a70 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
32a80 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
32a90 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
32aa0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
32ab0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
32ac0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
32ad0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
32ae0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
32af0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
32b00 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
32b10 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
32b20 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
32b30 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
32b40 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
32b50 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
32b60 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
32b70 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
32b80 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
32b90 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
32ba0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
32bb0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
32bc0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
32bd0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
32be0 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
32bf0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
32c00 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
32c10 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
32c20 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
32c30 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
32c40 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
32c50 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
32c60 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
32c70 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
32c80 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
32c90 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
32ca0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
32cb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32cc0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
32cd0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
32ce0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
32cf0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
32d00 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
32d10 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
32d20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
32d30 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
32d40 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
32d50 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
32d60 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
32d70 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
32d80 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
32d90 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
32da0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32db0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
32dc0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32dd0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
32de0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
32df0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
32e00 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
32e10 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
32e20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
32e30 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
32e40 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
32e50 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
32e60 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
32e70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32e80 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
32e90 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
32ea0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
32eb0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
32ec0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
32ed0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
32ee0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
32ef0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
32f00 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
32f10 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32f20 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
32f30 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
32f40 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
32f50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32f60 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
32f70 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
32f80 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
32f90 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
32fa0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32fb0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
32fc0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
32fd0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
32fe0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
32ff0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
33000 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
33010 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
33020 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
33030 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
33040 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
33050 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
33060 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
33070 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
33080 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
33090 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
330a0 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
330b0 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
330c0 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
330d0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
330e0 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
330f0 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
33100 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
33110 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
33120 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
33130 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
33140 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
33150 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
33160 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
33170 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
33180 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
33190 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
331a0 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
331b0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
331c0 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
331d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
331e0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
331f0 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
33200 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
33210 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
33220 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
33230 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
33240 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
33250 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
33260 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
33270 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
33280 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
33290 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
332a0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
332b0 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
332c0 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
332d0 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
332e0 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
332f0 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
33300 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
33310 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
33320 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
33330 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
33340 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
33350 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
33360 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
33370 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
33380 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
33390 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
333a0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
333b0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
333c0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
333d0 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
333e0 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
333f0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
33400 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
33410 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
33420 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
33430 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
33440 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
33450 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
33460 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
33470 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
33480 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
33490 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
334a0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
334b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
334c0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
334d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
334e0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
334f0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
33500 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
33510 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
33520 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
33530 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
33540 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
33550 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
33560 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
33570 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
33580 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
33590 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
335a0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
335b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
335c0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
335d0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
335e0 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
335f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
33600 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
33610 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
33620 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
33630 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
33640 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
33650 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
33660 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33670 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
33680 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
33690 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
336a0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
336b0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
336c0 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
336d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
336e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
336f0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
33700 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
33710 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
33720 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
33730 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
33740 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
33750 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
33760 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
33770 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
33780 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
33790 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
337a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
337b0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
337c0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
337d0 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
337e0 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
337f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
33800 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
33810 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
33820 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
33830 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
33840 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
33850 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
33860 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33870 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
33880 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
33890 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
338a0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
338b0 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
338c0 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
338d0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
338e0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
338f0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
33900 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
33910 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
33920 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
33930 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
33940 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33950 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
33960 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
33970 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
33980 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
33990 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
339a0 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
339b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
339c0 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
339d0 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
339e0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
339f0 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
33a00 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
33a10 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
33a20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
33a30 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
33a40 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
33a50 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
33a60 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
33a70 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
33a80 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
33a90 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
33aa0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
33ab0 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
33ac0 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
33ad0 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
33ae0 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
33af0 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
33b00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33b10 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
33b20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
33b30 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
33b40 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
33b50 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
33b60 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33b70 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
33b80 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
33b90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
33ba0 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
33bb0 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
33bc0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
33bd0 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
33be0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
33bf0 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
33c00 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
33c10 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
33c20 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
33c30 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33c40 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
33c50 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
33c60 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
33c70 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
33c80 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
33c90 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
33ca0 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
33cb0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
33cc0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
33cd0 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
33ce0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
33cf0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
33d00 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
33d10 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
33d20 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
33d30 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
33d40 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
33d50 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
33d60 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
33d70 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
33d80 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33d90 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
33da0 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
33db0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
33dc0 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
33dd0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
33de0 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
33df0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
33e00 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
33e10 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33e20 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
33e30 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
33e40 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
33e50 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
33e60 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
33e70 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
33e80 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
33e90 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
33ea0 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
33eb0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
33ec0 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
33ed0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
33ee0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
33ef0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
33f00 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
33f10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
33f20 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
33f30 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
33f40 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
33f50 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
33f60 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
33f70 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
33f80 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
33f90 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33fa0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33fb0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
33fc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33fd0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
33fe0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
33ff0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
34000 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
34010 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
34020 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
34030 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
34040 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
34050 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
34060 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
34070 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
34080 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
34090 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
340a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
340b0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
340c0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
340d0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
340e0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
340f0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
34100 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
34110 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
34120 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
34130 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
34140 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34150 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34160 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
34170 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
34180 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
34190 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
341a0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
341b0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
341c0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
341d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
341e0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
341f0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
34200 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
34210 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
34220 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
34230 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
34240 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
34250 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
34260 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34270 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
34280 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
34290 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
342a0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
342b0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
342c0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
342d0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
342e0 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  on..*/.sqlite3 *
342f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
34300 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
34310 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
34320 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
34330 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
34340 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73   Data.**.** Thes
34350 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  e functions may 
34360 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d  be used by (non-
34370 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66  aggregate) SQL f
34380 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
34390 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
343a0 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
343b0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
343c0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
343d0 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
343e0 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
343f0 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
34400 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
34410 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
34420 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
34430 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
34440 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
34450 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
34460 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rved.  An exampl
34470 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68  e.** of where th
34480 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66  is might be usef
34490 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c  ul is in a regul
344a0 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
344b0 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  tching.** functi
344c0 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
344d0 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
344e0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
344f0 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  on can be stored
34500 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
34510 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
34520 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
34530 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73  ng.  .** Then as
34540 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74   long as the pat
34550 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61  tern string rema
34560 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a  ins the same,.**
34570 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   the compiled re
34580 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
34590 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
345a0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
345b0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
345c0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a   same function..
345d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
345e0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
345f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
34600 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
34610 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
34620 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
34630 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
34640 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
34650 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
34660 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
34670 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
34680 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34690 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69  ion. ^If there i
346a0 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a  s no metadata.**
346b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
346c0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72   the function ar
346d0 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c  gument, this sql
346e0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
346f0 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
34700 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
34710 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
34720 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
34730 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
34740 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
34750 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f  P as metadata fo
34760 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
34770 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
34780 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34790 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75  d function.  ^Su
347a0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
347b0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
347c0 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65  _auxdata(C,N) re
347d0 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20  turn P from the 
347e0 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
347f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34800 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c  ta(C,N,P,X) call
34810 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
34820 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20   is still valid 
34830 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68  or.** NULL if th
34840 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  e metadata has b
34850 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  een discarded..*
34860 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61  * ^After each ca
34870 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
34880 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
34890 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f  X) where X is no
348a0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74  t NULL,.** SQLit
348b0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
348c0 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
348d0 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72  ction X with par
348e0 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79  ameter P exactly
348f0 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74  .** once, when t
34900 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
34910 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c  iscarded..** SQL
34920 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64  ite is free to d
34930 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64  iscard the metad
34940 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c  ata at any time,
34950 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e   including: <ul>
34960 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68  .** <li> when th
34970 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
34980 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
34990 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a  er changes, or.*
349a0 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c  * <li> when [sql
349b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
349c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
349d0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ze()] is called 
349e0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
349f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f  SQL statement, o
34a00 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73  r.** <li> when s
34a10 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34a20 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ta() is invoked 
34a30 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d  again on the sam
34a40 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a  e parameter, or.
34a50 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74  ** <li> during t
34a60 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69  he original sqli
34a70 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34a80 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65  ) call when a me
34a90 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c  mory .**      al
34aa0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
34ab0 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a  ccurs. </ul>)^.*
34ac0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61  *.** Note the la
34ad0 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72  st bullet in par
34ae0 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65  ticular.  The de
34af0 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a  structor X in .*
34b00 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
34b10 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d  xdata(C,N,P,X) m
34b20 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69  ight be called i
34b30 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
34b40 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  re the.** sqlite
34b50 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
34b60 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20 72  interface even r
34b70 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73  eturns.  Hence s
34b80 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34b90 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  ta().** should b
34ba0 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68  e called near th
34bb0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e  e end of the fun
34bc0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
34bd0 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20  tion and the.** 
34be0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
34bf0 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ntation should n
34c00 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20  ot make any use 
34c10 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71  of P after.** sq
34c20 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
34c30 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c  a() has been cal
34c40 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  led..**.** ^(In 
34c50 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
34c60 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
34c70 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
34c80 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75   calls for.** fu
34c90 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
34ca0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69  s that are compi
34cb0 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74  le-time constant
34cc0 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74  s, including lit
34cd0 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
34ce0 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  nd [parameters] 
34cf0 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20  and expressions 
34d00 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68  composed from th
34d10 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e same.)^.**.** 
34d20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
34d30 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
34d40 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
34d50 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
34d60 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
34d70 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
34d80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
34d90 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
34da0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
34db0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34dc0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
34dd0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
34de0 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
34df0 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
34e00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34e10 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
34e20 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
34e30 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
34e40 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
34e50 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
34e60 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
34e70 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
34e80 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
34e90 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
34ea0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
34eb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
34ec0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
34ed0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
34ee0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
34ef0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
34f00 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
34f10 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
34f20 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
34f30 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
34f40 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
34f50 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
34f60 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
34f70 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
34f80 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
34f90 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
34fa0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
34fb0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
34fc0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
34fd0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
34fe0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
34ff0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
35000 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
35010 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
35020 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
35030 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
35040 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
35050 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
35060 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74   compilers..*/.t
35070 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
35080 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
35090 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
350a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
350b0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
350c0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
350d0 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
350e0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
350f0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
35100 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
35110 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35120 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
35130 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
35140 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
35150 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
35160 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
35170 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
35180 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
35190 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
351a0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
351b0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
351c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
351d0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
351e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
351f0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
35200 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
35210 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
35220 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
35230 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
35240 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
35250 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
35260 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
35270 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
35280 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
35290 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
352a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
352b0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
352c0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
352d0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
352e0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
352f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
35300 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35310 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
35320 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
35330 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
35340 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
35350 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35360 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
35370 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
35380 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
35390 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
353a0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
353b0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
353c0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
353d0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
353e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
353f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
35400 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
35410 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
35420 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
35430 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35440 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
35450 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
35460 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
35470 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
35480 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
35490 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
354a0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
354b0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
354c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
354d0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
354e0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
354f0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
35500 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35510 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
35520 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
35530 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
35540 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
35550 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
35560 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35570 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
35580 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35590 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
355a0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
355b0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
355c0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
355d0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
355e0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
355f0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
35600 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
35610 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
35620 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35630 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
35640 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
35650 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
35660 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
35670 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
35680 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
35690 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
356a0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
356b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
356c0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
356d0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
356e0 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
356f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35700 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
35710 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
35720 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
35730 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
35740 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
35750 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
35760 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
35770 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
35780 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
35790 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
357a0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
357b0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
357c0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
357d0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
357e0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
357f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
35800 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35810 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
35820 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35830 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
35840 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
35850 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
35860 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
35870 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
35880 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
35890 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
358a0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
358b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
358c0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
358d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
358e0 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
358f0 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
35900 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
35910 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
35920 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
35930 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
35940 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
35950 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
35960 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
35970 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
35980 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
35990 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
359a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
359b0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
359c0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
359d0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
359e0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
359f0 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
35a00 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
35a10 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
35a20 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
35a30 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
35a40 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
35a50 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
35a60 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
35a70 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
35a80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35a90 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
35aa0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
35ab0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
35ac0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35ad0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
35ae0 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
35af0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
35b00 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
35b10 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
35b20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
35b30 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e   BLOB is too lon
35b40 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  g to represent..
35b50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35b60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
35b70 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
35b80 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
35b90 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
35ba0 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
35bb0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
35bc0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
35bd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35be0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
35bf0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
35c00 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
35c10 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
35c20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35c30 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
35c40 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
35c50 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
35c60 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
35c70 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
35c80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35c90 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
35ca0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
35cb0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
35cc0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35cd0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35ce0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
35cf0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
35d00 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
35d10 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
35d20 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
35d30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35d40 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
35d50 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
35d60 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
35d70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35d80 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35d90 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
35da0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35db0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
35dc0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35dd0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
35de0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
35df0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
35e00 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
35e10 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
35e20 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
35e30 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
35e40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35e50 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
35e60 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
35e70 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
35e80 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
35e90 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
35ea0 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
35eb0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
35ec0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
35ed0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
35ee0 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ely..** ^The sql
35ef0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35f00 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
35f10 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
35f20 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70  alue of an.** ap
35f30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35f40 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35f50 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 69   a text string i
35f60 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  n an encoding.**
35f70 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
35f80 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73  e fifth (and las
35f90 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68  t) parameter, wh
35fa0 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a  ich must be one.
35fb0 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ** of [SQLITE_UT
35fc0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
35fd0 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
35fe0 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
35ff0 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e  E_UTF16LE]..** ^
36000 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
36010 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
36020 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
36030 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
36040 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
36050 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36060 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
36070 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
36080 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
36090 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
360a0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
360b0 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
360c0 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
360d0 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
360e0 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
360f0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
36100 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
36110 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
36120 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
36130 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
36140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36150 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
36160 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
36170 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
36180 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
36190 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
361a0 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
361b0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
361c0 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
361d0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
361e0 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
361f0 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
36200 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
36210 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
36220 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
36230 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
36240 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
36250 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
36260 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
36270 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
36280 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
36290 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
362a0 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
362b0 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
362c0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
362d0 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
362e0 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
362f0 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
36300 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
36310 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
36320 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
36330 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
36340 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
36350 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
36360 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
36370 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
36380 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
36390 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
363a0 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
363b0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
363c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
363d0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
363e0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
363f0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
36400 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
36410 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
36420 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
36430 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
36440 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
36450 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
36460 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
36470 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
36480 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
36490 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
364a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
364b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
364c0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
364d0 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
364e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
364f0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
36500 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
36510 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
36520 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
36530 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
36540 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
36550 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
36560 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
36570 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
36580 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
36590 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
365a0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
365b0 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
365c0 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
365d0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
365e0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
365f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
36600 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36610 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
36620 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
36630 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
36640 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
36650 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
36660 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
36670 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
36680 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
36690 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
366a0 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
366b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
366c0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
366d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
366e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
366f0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
36700 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
36710 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
36720 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36730 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
36740 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
36750 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
36760 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
36770 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
36780 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
36790 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
367a0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
367b0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
367c0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
367d0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
367e0 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
367f0 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
36800 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
36810 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
36820 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
36830 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
36840 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
36850 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
36860 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
36870 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36880 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
36890 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
368a0 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
368b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
368c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
368d0 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
368e0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
368f0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
36900 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
36910 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
36920 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
36930 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
36940 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
36950 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
36960 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
36970 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
36980 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
36990 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
369a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
369b0 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
369c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
369d0 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
369e0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
369f0 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
36a00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36a10 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
36a20 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36a30 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
36a40 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
36a50 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
36a60 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
36a70 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  xt*,const void*,
36a80 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
36a90 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
36aa0 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64 28  te3_uint64,void(
36ab0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
36ac0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36ad0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
36ae0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
36af0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36b00 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
36b10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
36b20 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
36b30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36b40 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
36b50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36b60 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
36b70 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36b80 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
36b90 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
36ba0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
36bb0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36bc0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
36bd0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
36be0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36bf0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
36c00 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
36c10 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36c20 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
36c30 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
36c40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36c50 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
36c60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
36c70 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
36c80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36c90 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
36ca0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
36cb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36cc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36cd0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
36ce0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
36cf0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
36d00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34  e3_result_text64
36d10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36d20 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  *, const char*,s
36d30 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
36d40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36d50 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
36d60 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
36d70 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
36d80 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36d90 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
36da0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36db0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
36dc0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
36dd0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36de0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
36df0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36e00 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
36e10 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
36e20 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
36e30 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
36e40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36e50 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
36e60 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
36e70 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
36e80 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
36e90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36ea0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
36eb0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36ec0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
36ed0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36ee0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
36ef0 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
36f00 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
36f10 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e  equences.**.** ^
36f20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
36f30 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20  add, remove, or 
36f40 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74  modify a [collat
36f50 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a  ion] associated.
36f60 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
36f70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36f80 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
36f90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
36fa0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
36fb0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  me of the collat
36fc0 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73  ion is a UTF-8 s
36fd0 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
36fe0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36ff0 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
37000 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37010 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
37020 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
37030 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
37040 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
37050 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37060 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  on16()..** ^Coll
37070 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74  ation names that
37080 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61   compare equal a
37090 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c  ccording to [sql
370a0 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d  ite3_strnicmp()]
370b0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
370c0 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d  ed to be the sam
370d0 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e name..**.** ^(
370e0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
370f0 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75  nt (eTextRep) mu
37100 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  st be one of the
37110 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c   constants:.** <
37120 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
37130 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c  ITE_UTF8],.** <l
37140 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
37150 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  LE],.** <li> [SQ
37160 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
37170 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
37180 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  TF16], or.** <li
37190 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  > [SQLITE_UTF16_
371a0 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75  ALIGNED]..** </u
371b0 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65  l>)^.** ^The eTe
371c0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64  xtRep argument d
371d0 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e  etermines the en
371e0 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67  coding of string
371f0 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74  s passed.** to t
37200 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
37210 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20  ction callback, 
37220 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54  xCallback..** ^T
37230 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
37240 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54  ] and [SQLITE_UT
37250 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
37260 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70  ues for eTextRep
37270 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67  .** force string
37280 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69  s to be UTF16 wi
37290 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  th native byte o
372a0 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  rder..** ^The [S
372b0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
372c0 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65  NED] value for e
372d0 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73  TextRep forces s
372e0 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a  trings to begin.
372f0 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79  ** on an even by
37300 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a  te address..**.*
37310 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72  * ^The fourth ar
37320 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73  gument, pArg, is
37330 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
37340 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
37350 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  t is passed.** t
37360 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
37370 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
37380 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
37390 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  nction callback.
373a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
373b0 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c  h argument, xCal
373c0 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e  lback, is a poin
373d0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ter to the colla
373e0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ting function..*
373f0 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c  * ^Multiple coll
37400 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
37410 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
37420 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  d using the same
37430 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74   name but.** wit
37440 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  h different eTex
37450 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20  tRep parameters 
37460 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  and SQLite will 
37470 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a  use whichever.**
37480 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
37490 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
374a0 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e  unt of data tran
374b0 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  sformation..** ^
374c0 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b  If the xCallback
374d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c   argument is NUL
374e0 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  L then the colla
374f0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
37500 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57  .** deleted.  ^W
37510 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e  hen all collatin
37520 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69  g functions havi
37530 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
37540 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a   are deleted,.**
37550 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20   that collation 
37560 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61  is no longer usa
37570 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
37580 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37590 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  on callback is i
375a0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f  nvoked with a co
375b0 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a  py of the pArg .
375c0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  ** application d
375d0 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ata pointer and 
375e0 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73  with two strings
375f0 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
37600 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
37610 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72   the eTextRep ar
37620 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c  gument.  The col
37630 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37640 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a  must return an.*
37650 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69  * integer that i
37660 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  s negative, zero
37670 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a  , or positive.**
37680 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74   if the first st
37690 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
376a0 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
376b0 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
376c0 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70   second,.** resp
376d0 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c  ectively.  A col
376e0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
376f0 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75  must always retu
37700 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77  rn the same answ
37710 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20  er.** given the 
37720 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66  same inputs.  If
37730 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c   two or more col
37740 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
37750 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a   are registered.
37760 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63  ** to the same c
37770 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75  ollation name (u
37780 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65  sing different e
37790 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20  TextRep values) 
377a0 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74  then all.** must
377b0 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c   give an equival
377c0 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20  ent answer when 
377d0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75  invoked with equ
377e0 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e  ivalent strings.
377f0 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  .** The collatin
37800 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
37810 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69  obey the followi
37820 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f  ng properties fo
37830 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73  r all.** strings
37840 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a   A, B, and C:.**
37850 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
37860 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d   If A==B then B=
37870 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =A..** <li> If A
37880 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65  ==B and B==C the
37890 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20  n A==C..** <li> 
378a0 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42  If A&lt;B THEN B
378b0 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49  &gt;A..** <li> I
378c0 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c  f A&lt;B and B&l
378d0 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e  t;C then A&lt;C.
378e0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
378f0 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66  If a collating f
37900 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e  unction fails an
37910 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63  y of the above c
37920 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
37930 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67  hat.** collating
37940 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65   function is  re
37950 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65  gistered and use
37960 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
37970 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
37980 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
37990 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
379a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
379b0 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
379c0 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
379d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
379e0 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74  * with the addit
379f0 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65  ion that the xDe
37a00 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
37a10 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72  s invoked on pAr
37a20 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  g when.** the co
37a30 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37a40 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   is deleted..** 
37a50 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74  ^Collating funct
37a60 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64  ions are deleted
37a70 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
37a80 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
37a90 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74  er.** calls to t
37aa0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
37ab0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
37ac0 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  or when the.** [
37ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37ae0 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75  ion] is closed u
37af0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
37b00 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ose()]..**.** ^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 3c 75 3e 6e 6f 74 3c 2f  back is <u>not</
37b30 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65  u> called if the
37b40 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65   .** sqlite3_cre
37b50 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
37b60 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  () function fail
37b70 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  s.  Applications
37b80 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20   that invoke.** 
37b90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37ba0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69  ollation_v2() wi
37bb0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44  th a non-NULL xD
37bc0 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20  estroy argument 
37bd0 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b  should .** check
37be0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
37bf0 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20   and dispose of 
37c00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
37c10 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  data pointer.** 
37c20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65  themselves rathe
37c30 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67  r than expecting
37c40 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20   SQLite to deal 
37c50 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d  with it for them
37c60 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66  ..** This is dif
37c70 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72  ferent from ever
37c80 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
37c90 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69  nterface.  The i
37ca0 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a  nconsistency .**
37cb0 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20   is unfortunate 
37cc0 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  but cannot be ch
37cd0 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72  anged without br
37ce0 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73  eaking backwards
37cf0 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69   .** compatibili
37d00 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ty..**.** See al
37d10 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
37d20 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
37d30 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
37d40 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
37d50 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
37d60 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37d70 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
37d80 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
37d90 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
37da0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
37db0 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
37dc0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
37dd0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
37de0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
37df0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
37e00 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
37e10 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
37e20 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
37e30 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
37e40 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
37e50 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
37e60 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
37e70 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
37e80 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
37e90 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
37ea0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
37eb0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37ec0 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
37ed0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
37ee0 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
37ef0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
37f00 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
37f10 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
37f20 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
37f30 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
37f40 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
37f50 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
37f60 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
37f70 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76  cks.**.** ^To av
37f80 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
37f90 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
37fa0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
37fb0 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
37fc0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
37fd0 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
37fe0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
37ff0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
38000 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
38010 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38020 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
38030 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
38040 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
38050 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
38060 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uired..**.** ^If
38070 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
38080 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
38090 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
380a0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
380b0 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
380c0 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
380d0 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
380e0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
380f0 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
38100 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
38110 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65  TF-8. ^If sqlite
38120 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
38130 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
38140 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
38150 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
38160 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
38170 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
38180 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69  ** ^A call to ei
38190 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
381a0 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74  places the exist
381b0 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65  ing collation-ne
381c0 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  eded callback..*
381d0 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20  *.** ^(When the 
381e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
381f0 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
38200 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
38210 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
38220 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
38230 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
38240 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
38250 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
38260 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
38270 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
38280 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
38290 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
382a0 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
382b0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
382c0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
382d0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
382e0 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
382f0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
38300 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
38310 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
38320 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
38330 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
38340 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
38350 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
38360 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
38370 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
38380 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
38390 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a  n sequence.)^.**
383a0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
383b0 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
383c0 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
383d0 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
383e0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
383f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
38400 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
38410 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
38420 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
38430 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
38440 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
38450 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
38460 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
38470 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
38480 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
38490 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
384a0 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
384b0 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20  t char*).);.int 
384c0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
384d0 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
384e0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
384f0 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
38500 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
38510 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
38520 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20  id*).);..#ifdef 
38530 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43  SQLITE_HAS_CODEC
38540 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
38550 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
38560 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
38570 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
38580 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
38590 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
385a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
385b0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
385c0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
385d0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
385e0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
385f0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
38600 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
38610 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
38620 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
38630 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
38640 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
38650 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
38660 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
38670 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
38680 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e  The key */.);.in
38690 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32  t sqlite3_key_v2
386a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
386b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
386c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
386d0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
386e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
386f0 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20  bName,          
38700 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
38710 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
38720 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
38730 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
38740 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
38750 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
38760 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
38770 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
38780 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
38790 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
387a0 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
387b0 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
387c0 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
387d0 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
387e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
387f0 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
38800 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
38810 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
38820 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available