/ Hex Artifact Content
Login

Artifact 7e7ce8ea342d59f109dcf3185374ebe1a6c0e4dd:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  y are supported 
07d0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
07e0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
07f0: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
0800: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
0810: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
0820: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
0830: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
0840: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
0850: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
0860: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
0870: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
0880: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
0890: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
08a0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
08b0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
08c0: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
08d0: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
08e0: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
08f0: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
0900: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
0910: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
0920: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
0930: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
0940: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
0950: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
0960: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
0970: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
0980: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0990: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
09a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
09b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
09c0: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
09d0: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
09e0: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
09f0: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
0a00: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
0a10: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
0a20: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0a30: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
0a40: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0a50: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
0a60: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a70: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
0a80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0a90: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
0aa0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0ab0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
0ac0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ad0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0ae0: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
0af0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
0b00: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
0b10: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0b20: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0b30: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
0b40: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
0b50: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
0b60: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0b70: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
0b80: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
0b90: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
0ba0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0bb0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
0bc0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0bd0: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
0be0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bf0: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
0c00: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
0c10: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
0c20: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
0c30: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0c40: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0c50: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
0c60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
0c70: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
0c80: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
0c90: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0ca0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
0cb0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
0cc0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
0cd0: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
0ce0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
0cf0: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
0d00: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
0d10: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
0d20: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
0d30: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
0d40: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
0d50: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
0d60: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
0d70: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
0d80: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
0d90: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
0da0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
0db0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
0dc0: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
0dd0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
0de0: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
0df0: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
0e00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0e10: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
0e20: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
0e30: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
0e40: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
0e50: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
0e60: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
0e70: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
0e80: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
0e90: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
0ea0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
0eb0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
0ec0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
0ed0: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
0ee0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
0ef0: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
0f00: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
0f10: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
0f20: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
0f30: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
0f40: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0f50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0f60: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
0f70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0f80: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
0f90: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
0fa0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
0fb0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
0fc0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
0fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
0fe0: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
0ff0: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69  "--VERS--".#defi
1000: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1010: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49  N_NUMBER --VERSI
1020: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66  ON-NUMBER--.#def
1030: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1040: 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55  E_ID      "--SOU
1050: 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a  RCE-ID--"../*.**
1060: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1070: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
1080: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
1090: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10a0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
10b0: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
10c0: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
10d0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
10e0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
10f0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1100: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1110: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1120: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1130: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1140: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
1150: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
1160: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1170: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
1180: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
1190: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11a0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
11b0: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
11c0: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
11d0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
11e0: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
11f0: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1200: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1210: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1220: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1230: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1240: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
1250: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
1260: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
1270: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
1280: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
1290: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12b0: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
12c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
12d0: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
12e0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
12f0: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1300: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1310: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1320: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1330: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1340: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
1350: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
1360: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1370: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1380: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1390: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13a0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
13b0: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
13c0: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
13d0: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
13e0: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
13f0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1400: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1410: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1420: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1430: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1440: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
1450: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1460: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
1470: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
1480: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1490: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14a0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
14b0: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
14c0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
14d0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
14e0: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
14f0: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1510: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1520: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1530: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1540: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
1550: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
1560: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
1570: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
1580: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
1590: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15a0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
15b0: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
15c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
15d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
15e0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
15f0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1600: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1610: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1620: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ()]..*/.SQLITE_E
1630: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
1640: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1650: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
1660: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1670: 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20  on(void);.const 
1680: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1690: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e  urceid(void);.in
16a0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
16b0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
16c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16d0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
16e0: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
16f0: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1700: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1710: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1720: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1730: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1740: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1750: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1760: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
1770: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
1780: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1790: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
17a0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
17b0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
17c0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
17d0: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
17e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
17f0: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1800: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1810: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1820: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1830: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1840: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1850: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1860: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
1870: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
1880: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
18a0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
18b0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
18c0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
18d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
18e0: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
18f0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1900: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1910: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1920: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1930: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1940: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1950: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1960: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1970: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1980: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
19a0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
19b0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19c0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
19d0: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
19e0: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
19f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1a00: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1a10: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1a20: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1a30: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1a40: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1a50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a60: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1a80: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1a90: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1aa0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1ab0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1ac0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1ad0: 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65  DIAGS.int sqlite
1ae0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1af0: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20  used(const char 
1b00: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73  *zOptName);.cons
1b10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1b20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1b40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1b60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1b70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1b80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1b90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1ba0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1bb0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1bc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1bd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1be0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1bf0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1c00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1c10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1c20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1c30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1c40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1c50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1c60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1c70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1c80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1c90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ca0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1cb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1cc0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1cd0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ce0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1cf0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1d10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1d20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1d30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1d40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1d50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1d60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1d70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1d80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1d90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1da0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1db0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1dc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1dd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1de0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1df0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1e00: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1e10: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1e20: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1e30: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1e40: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1e50: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
1e60: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
1e70: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
1e80: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
1e90: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1ea0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
1eb0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
1ec0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1ed0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
1ee0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
1ef0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
1f00: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
1f10: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
1f20: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
1f30: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f40: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
1f50: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
1f60: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
1f70: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
1f80: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
1f90: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1fa0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
1fb0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1fc0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
1fd0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fe0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
1ff0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2000: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2010: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2020: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2030: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2040: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2050: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2060: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2080: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
20a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
20b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
20c0: 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65  IALIZED].  ^(The
20d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
20e0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
20f0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
2100: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
2110: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2120: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
2130: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
2140: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
2150: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
2160: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
2170: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
2180: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
2190: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
21a0: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
21b0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
21c0: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
21d0: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
21e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
21f0: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
2200: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
2210: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2220: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2230: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  rmation..*/.int 
2240: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2250: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
2260: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
2270: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
2280: 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  andle.** KEYWORD
2290: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
22a0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
22b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
22c0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
22d0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
22e0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
22f0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
2300: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
2310: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
2320: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
2330: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
2340: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
2350: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
2360: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
2370: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
2380: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2390: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
23a0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
23b0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
23c0: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
23d0: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
23e0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
23f0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2400: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72  3_close_v2()] ar
2410: 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  e its destructor
2420: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  s.  There are ma
2430: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65  ny other.** inte
2440: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
2450: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2460: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2470: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2480: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
2490: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
24a0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
24b0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
24c0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
24d0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
24e0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
24f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
2500: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
2510: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
2520: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a  Integer Types.**
2530: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
2540: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
2550: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
2560: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
2570: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
2580: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
2590: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
25a0: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
25b0: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
25c0: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
25d0: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
25e0: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
25f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
2600: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
2610: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
2620: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69  rred type defini
2630: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71  tions..** The sq
2640: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
2650: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2660: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  es are supported
2670: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
2680: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
2690: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
26a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
26b0: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  nd sqlite_int64 
26c0: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
26d0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a  integer values.*
26e0: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33  * between -92233
26f0: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61  72036854775808 a
2700: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35  nd +922337203685
2710: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76  4775807 inclusiv
2720: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2730: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73  te3_uint64 and s
2740: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2750: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2760: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20  eger values .** 
2770: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31  between 0 and +1
2780: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31  8446744073709551
2790: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a  615 inclusive..*
27a0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
27b0: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
27c0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
27d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
27e0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
27f0: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
2800: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2810: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
2820: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2830: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2840: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2850: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2860: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2870: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2880: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2890: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
28a0: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
28b0: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
28c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
28d0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
28e0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28f0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2900: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2910: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2920: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2930: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2940: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2950: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2960: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2970: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2980: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2990: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
29a0: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
29b0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
29c0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
29d0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
29e0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
29f0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2a00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2a10: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2a20: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
2a30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2a40: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2a50: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2a60: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2a70: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2a80: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2a90: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2aa0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ab0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2ac0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2ad0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2ae0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2af0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2b00: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2b10: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2b20: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2b30: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2b40: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2b50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b60: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2b70: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2b80: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2b90: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ba0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2bb0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2bc0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2bd0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2c00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2c10: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2c20: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2c30: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2c40: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2c50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2c60: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2c70: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2c80: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2c90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ca0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2cb0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2cc0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2cd0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ce0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2cf0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2d00: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2d10: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2d20: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2d30: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2d40: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2d50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2d60: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2d70: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2d80: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2d90: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2da0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2db0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2dc0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2dd0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2de0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2df0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2e00: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
2e10: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e20: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2e30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e40: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
2e50: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
2e60: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
2e70: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
2e80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
2e90: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
2ea0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
2eb0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
2ec0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
2ed0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
2ee0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
2ef0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
2f00: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
2f10: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
2f20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
2f30: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f50: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2f60: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
2f70: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f80: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
2f90: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
2fa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
2fb0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
2fc0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
2fd0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
2fe0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
2ff0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3000: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3010: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3020: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3030: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3040: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3050: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3060: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3070: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3080: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3090: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
30a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
30b0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
30c0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
30d0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
30e0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
30f0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3100: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3110: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3120: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3130: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3140: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3150: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3160: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3170: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
31a0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
31b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
31c0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
31d0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
31e0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
31f0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3200: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3210: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3220: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3230: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3240: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3250: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3260: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3270: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3280: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3290: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
32a0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
32b0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
32c0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
32d0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
32e0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
32f0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3300: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3310: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3320: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3330: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3340: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3350: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3360: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3370: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3380: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
3390: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
33a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
33b0: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
33c0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
33d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
33f0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
3400: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
3410: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3420: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3430: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3440: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3450: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3460: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3470: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3480: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3490: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
34a0: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
34b0: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
34c0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
34d0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
34e0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
34f0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
3500: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
3510: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3520: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3530: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3540: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3550: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3580: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3590: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
35a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
35b0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
35c0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
35d0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
35e0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
35f0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
3600: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3610: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3620: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3630: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3640: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3650: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3660: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3670: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3680: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3690: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
36a0: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
36b0: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
36c0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
36d0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
36e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
36f0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3700: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3710: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3720: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3730: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3740: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3750: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3760: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3770: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3780: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3790: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
37a0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
37b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
37c0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
37d0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
37e0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
37f0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3800: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3810: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3820: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3830: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3840: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3850: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3860: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3870: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3880: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3890: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
38a0: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
38b0: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
38c0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
38d0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
38e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
38f0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3900: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3910: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3920: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3930: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3950: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3960: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3970: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3980: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3990: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
39a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
39b0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
39c0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
39d0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
39e0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
39f0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3a00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3a10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3a20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3a30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3a40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3a50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3a60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3a70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3a80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3a90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3aa0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3ab0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3ac0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3ad0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ae0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3af0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3b00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3b20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3b30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3b40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3b50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3b60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3b70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3b80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3b90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ba0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3bb0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3bc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3bd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3be0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3c10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3c20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3c30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3c40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3c50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3c60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3c70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3c80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3c90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ca0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3cb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3cc0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3cd0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ce0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3cf0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3d00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3d10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3d20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3d30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3d40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3d50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3d60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3d70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3d80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3d90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3da0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3db0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3dc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3dd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3de0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3df0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
3e00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e10: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
3e20: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3e30: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3e40: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
3e50: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3e70: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3e80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e90: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
3ea0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3eb0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3ec0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3ed0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3ef0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3f00: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3f10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3f20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3f30: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3f40: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3f50: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3f60: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3f70: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3f80: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3f90: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3fa0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3fb0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
3fc0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
3fd0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ff0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4000: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4010: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4040: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4050: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4060: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4070: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4080: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4090: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
40d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
40e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
40f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4110: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4120: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4130: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4140: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4150: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4160: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4170: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4180: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4190: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
41e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
41f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4200: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4210: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4220: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4230: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4240: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4250: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4260: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4270: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4280: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4290: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
42a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
42b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
42c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
42d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
42e0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
42f0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
4300: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4310: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4320: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4330: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4340: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4350: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4360: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4370: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4380: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4390: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
43a0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
43b0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
43c0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
43f0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4400: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4420: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4430: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4440: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4450: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4460: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4470: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4480: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
44b0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
44c0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
44d0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
44e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
44f0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4500: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4510: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4520: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4540: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4550: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4560: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4570: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4580: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4590: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
45a0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
45b0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
45e0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
45f0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4600: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4610: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4620: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4630: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4640: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4650: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4660: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4670: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4680: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4690: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
46a0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
46b0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
46c0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
46d0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
46e0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
46f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4700: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4710: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4720: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4730: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4740: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4750: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4760: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4770: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4780: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4790: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
47a0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
47b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47c0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
47d0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
47e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
47f0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4800: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4810: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4820: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4830: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4840: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4850: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4860: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4880: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4890: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
48a0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
48b0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
48c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
48d0: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
48e0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
48f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4900: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4910: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4920: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4930: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4950: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4960: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4970: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4980: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
49a0: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
49b0: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
49c0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
49d0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
49e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49f0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4a00: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4a10: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4a20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4a30: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4a40: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4a50: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4a60: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4a70: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4a80: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4a90: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4aa0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4ab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ac0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ad0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4ae0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4af0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4b00: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4b10: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4b20: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4b30: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4b40: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b50: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b60: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4b70: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4b80: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4b90: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4ba0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4bb0: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4bc0: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4bd0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4be0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4bf0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4c00: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4c10: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4c20: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4c30: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4c40: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4c50: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4c60: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4c70: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4c80: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4c90: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4ca0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4cb0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4cc0: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4cd0: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4ce0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4cf0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4d00: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4d10: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4d20: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4d30: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4d40: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65  ese [extended re
4d50: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
4d60: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4d70: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4d80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4d90: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4da0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4db0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4dc0: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f  codes()] API.  O
4dd0: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20  r, the extended 
4de0: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
4df0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
4e00: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  r can be obtaine
4e10: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
4e20: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
4e30: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  code()]..*/.#def
4e40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e50: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
4e60: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e70: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
4e80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4e90: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
4ea0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4eb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
4ec0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
4ed0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
4ee0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4ef0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
4f00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
4f10: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
4f20: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f30: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
4f50: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
4f60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f70: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
4f90: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
4fa0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
4fb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
4fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fe0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
4ff0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5000: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
5010: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5020: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
5030: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5040: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
5050: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5060: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5070: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5080: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5090: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
50b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
50d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
50f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5100: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
5110: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5120: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
5130: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5140: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
5150: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5160: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5170: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5180: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5190: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
51a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
51b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51c0: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
51d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
51f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5200: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
5210: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5220: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
5230: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5240: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
5250: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
5260: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
5270: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5280: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
5290: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
52b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
52c0: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
52d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
52f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5300: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
5310: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5320: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
5330: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5340: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
5350: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5360: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
5390: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
53b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53c0: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
53d0: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
53e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
53f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5400: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
5410: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5420: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
5430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5440: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
5450: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5460: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
5470: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5480: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
5490: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
54a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
54b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54c0: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
54d0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
54e0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
54f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5500: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
5510: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5520: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
5530: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5540: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f  ITE_BUSY_SNAPSHO
5550: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  T           (SQL
5560: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32  ITE_BUSY   |  (2
5570: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5580: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5590: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
55a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
55b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
55c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
55d0: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
55e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
55f0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5600: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5610: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20  N_FULLPATH      
5620: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5630: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  N | (3<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5650: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  PEN_CONVPATH    
5660: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5670: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  PEN | (4<<8)).#d
5680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
5690: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
56a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
56b0: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
56c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
56d0: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
56e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
56f0: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
5720: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5730: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
5740: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5750: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42  E_READONLY_ROLLB
5760: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  ACK       (SQLIT
5770: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c  E_READONLY | (3<
5780: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5790: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d  ITE_READONLY_DBM
57a0: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c  OVED        (SQL
57b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57c0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
57d0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
57e0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
57f0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5800: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5810: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5820: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5830: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5840: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5850: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5860: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5870: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5880: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
58a0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
58b0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
58c0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
58d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58e0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
58f0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5900: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5910: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5920: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5930: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5940: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5950: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5960: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5970: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5980: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5990: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
59a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59b0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
59c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59d0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
59e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
59f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5a00: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5a20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a30: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a40: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a60: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5a70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a80: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
5a90: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5aa0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
5ab0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5ac0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
5ad0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
5ae0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
5af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5b00: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
5b10: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
5b20: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
5b30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
5b40: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
5b50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
5b60: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
5b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
5b80: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
5b90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
5ba0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  TH | (1<<8))../*
5bb0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
5bc0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
5bd0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
5be0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
5bf0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
5c00: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
5c10: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5c20: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5c30: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5c40: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5c50: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5c60: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5c70: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
5c80: 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  hod..*/.#define 
5c90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5ca0: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
5cb0: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66  0000001  /* Ok f
5cc0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5cd0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5cf0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
5d00: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66  0000002  /* Ok f
5d10: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d20: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
5d40: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
5d50: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66  0000004  /* Ok f
5d60: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d70: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
5d90: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
5da0: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20  0000008  /* VFS 
5db0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5dc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
5dd0: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
5de0: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20  0000010  /* VFS 
5df0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f  SQLITE_OPEN_AUTO
5e10: 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30  PROXY        0x0
5e20: 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20  0000020  /* VFS 
5e30: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
5e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5e60: 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66  0000040  /* Ok f
5e70: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5e80: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5e90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f  SQLITE_OPEN_MEMO
5ea0: 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30  RY           0x0
5eb0: 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66  0000080  /* Ok f
5ec0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5ed0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ee0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5ef0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f00: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20  0000100  /* VFS 
5f10: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5f30: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f40: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20  0000200  /* VFS 
5f50: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
5f70: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
5f80: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20  0000400  /* VFS 
5f90: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5fb0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
5fc0: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20  0000800  /* VFS 
5fd0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fe0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5ff0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
6000: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20  0001000  /* VFS 
6010: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6020: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
6030: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
6040: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20  0002000  /* VFS 
6050: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
6070: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
6080: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20  0004000  /* VFS 
6090: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
60a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
60b0: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
60c0: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0008000  /* Ok f
60d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
60e0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
60f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
6100: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
6110: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0010000  /* Ok f
6120: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6130: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6140: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
6150: 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30  EDCACHE      0x0
6160: 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0020000  /* Ok f
6170: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6180: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6190: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
61a0: 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30  ATECACHE     0x0
61b0: 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0040000  /* Ok f
61c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
61d0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
61e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20  SQLITE_OPEN_WAL 
61f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6200: 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20  0080000  /* VFS 
6210: 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65  only */../* Rese
6220: 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20  rved:           
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6240: 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a  00F00000 */../*.
6250: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
6260: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
6270: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
6280: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6290: 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  tics method of t
62a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
62b0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
62c0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
62d0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
62e0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a  vector of these.
62f0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
6300: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
6310: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
6320: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
6330: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
6340: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
6350: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
6360: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6370: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
63a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
63b0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
63c0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
63d0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
63e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
63f0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6400: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6410: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6420: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6430: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6440: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6450: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6460: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6470: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6480: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6490: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
64a0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
64b0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
64c0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
64d0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
64e0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
64f0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6500: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6510: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6520: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6530: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6550: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6560: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6570: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6580: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6590: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
65a0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
65b0: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
65c0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
65d0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
65e0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
65f0: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
6600: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
6610: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
6620: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
6630: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
6640: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
6650: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
6660: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
6670: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
6680: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
6690: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
66a0: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
66b0: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
66c0: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
66d0: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  be unchanged.  T
66e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66f0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6700: 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e  _OPEN.** flag in
6710: 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69  dicate that a fi
6720: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6730: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6740: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6750: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6760: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6770: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6780: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6790: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
67a0: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
67b0: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
67c0: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
67d0: 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65  ivileges..*/.#de
67e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
67f0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6800: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6810: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6830: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6840: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6850: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6860: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6870: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6880: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6890: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
68a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
68b0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
68c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
68d0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
68e0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
68f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6900: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6910: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6920: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6940: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6950: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6970: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6980: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6990: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
69a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69b0: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
69c0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
69d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
69f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6a00: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a10: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6a20: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6a30: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6a40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6a50: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6a60: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a80: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6a90: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6aa0: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6ac0: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
6ad0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a      0x00002000..
6ae0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6af0: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6b00: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
6b10: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
6b20: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6b30: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
6b40: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
6b50: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
6b60: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
6b70: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
6b80: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
6b90: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6ba0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
6bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6bc0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6be0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
6bf0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
6c00: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6c10: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6c20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6c30: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
6c40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6c50: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
6c60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c70: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
6c80: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
6c90: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
6ca0: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
6cb0: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
6cc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6cd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6ce0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6cf0: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6d00: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6d10: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
6d20: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
6d30: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
6d40: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
6d50: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
6d60: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
6d70: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
6d80: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
6d90: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
6da0: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
6db0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
6dc0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
6dd0: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
6de0: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
6df0: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
6e00: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e10: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
6e20: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6e30: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
6e40: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6e50: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
6e60: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6e70: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
6e80: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
6e90: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
6ea0: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
6eb0: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
6ec0: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
6ed0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6ee0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6ef0: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
6f00: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
6f10: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
6f20: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
6f30: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
6f40: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
6f50: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
6f60: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
6f70: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
6f80: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
6f90: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
6fa0: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
6fb0: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
6fc0: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
6fd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6fe0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6ff0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
7000: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
7010: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
7020: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
7030: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
7040: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
7050: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
7060: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
7070: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
7080: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
7090: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
70a0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
70b0: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
70c0: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
70d0: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
70e0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
70f0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7100: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
7110: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
7120: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
7130: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
7140: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
7150: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
7160: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
7170: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
7180: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7190: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
71a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71b0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
71c0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
71d0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
71e0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
71f0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
7200: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7210: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
7220: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
7230: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7240: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
7250: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
7260: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
7270: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
7280: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
7290: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
72a0: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
72b0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
72c0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
72d0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
72e0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
72f0: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
7300: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
7310: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
7320: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
7330: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
7340: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7350: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
7360: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
7370: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
7380: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
7390: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
73a0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
73b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
73c0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
73d0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
73e0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
73f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7400: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
7410: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
7420: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
7430: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7440: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
7450: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
7460: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
7470: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
7480: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7490: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
74a0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
74b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
74c0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
74d0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
74e0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
74f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7500: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
7510: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
7520: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
7530: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
7540: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7550: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
7560: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
7570: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
7580: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
7590: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
75a0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
75b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
75c0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
75d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
75e0: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
75f0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7600: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7610: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
7620: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
7630: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
7640: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
7650: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
7660: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
7670: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7680: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
7690: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
76a0: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
76b0: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
76c0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
76d0: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
76e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
76f0: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
7700: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7710: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
7720: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7730: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
7740: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
7750: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
7760: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
7770: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
7780: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
7790: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
77a0: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
77b0: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
77c0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
77d0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
77e0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
77f0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7800: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
7810: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7820: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
7830: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
7840: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
7850: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
7860: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
7870: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
7880: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
7890: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
78a0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
78b0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
78c0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
78d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
78e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
78f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7900: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7910: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7920: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
7930: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7940: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
7950: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7960: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
7970: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
7980: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
7990: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
79a0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
79b0: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
79c0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
79d0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
79e0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
79f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
7a00: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
7a10: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
7a20: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
7a30: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
7a40: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
7a50: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
7a60: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
7a70: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
7a80: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
7a90: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
7aa0: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
7ab0: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
7ac0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7ad0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
7ae0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
7af0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
7b00: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
7b10: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
7b20: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
7b30: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
7b40: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7b50: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
7b60: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
7b70: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
7b80: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
7b90: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
7ba0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
7bb0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
7bc0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
7bd0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
7be0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
7bf0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
7c00: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
7c10: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
7c20: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
7c30: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
7c40: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
7c50: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
7c60: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
7c70: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
7c80: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
7c90: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
7ca0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
7cb0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
7cc0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
7cd0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
7ce0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
7cf0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
7d00: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
7d10: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
7d20: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
7d30: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
7d40: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
7d50: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
7d60: 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63  se..** A [file c
7d70: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c  ontrol opcodes |
7d80: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7d90: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7da0: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7db0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7dc0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7dd0: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7de0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7df0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7e00: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7e10: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7e20: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7e30: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7e40: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7e50: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7e60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7e70: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7e80: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7e90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7ea0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7eb0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7ec0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7ed0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7ee0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7ef0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7f00: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7f10: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7f20: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7f30: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7f40: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7f50: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7f60: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7f70: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7f80: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7f90: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7fa0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7fb0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7fc0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7fd0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7fe0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7ff0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
8000: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8010: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
8040: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8050: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
8060: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8070: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
8080: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8090: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
80a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80b0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
80c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
80d0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
80e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80f0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
8100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8110: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
8120: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8130: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8140: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8150: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8160: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8170: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8180: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8190: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
81a0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
81b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
81c0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
81d0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
81e0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
81f0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
8200: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
8210: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
8220: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
8230: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8240: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8250: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8260: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8270: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8280: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8290: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
82a0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
82b0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
82c0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
82d0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
82e0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
82f0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8300: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8310: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8320: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
8330: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8340: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8350: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8360: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8370: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8380: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8390: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
83a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
83b0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
83c0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
83d0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
83e0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
83f0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
8400: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
8410: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
8420: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
8430: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8440: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8450: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8460: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8470: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8480: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8490: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
84a0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
84b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
84c0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
84d0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
84e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84f0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8500: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
8510: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
8520: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
8530: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8540: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8550: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8560: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8570: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8580: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8590: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
85a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
85b0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
85c0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
85d0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
85e0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
85f0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
8600: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
8610: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
8620: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
8630: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8640: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8650: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8660: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8670: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8680: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8690: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
86a0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
86b0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
86c0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
86e0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
86f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8700: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8710: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8720: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8730: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8740: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8750: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8760: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8770: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8780: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8790: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
87a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
87b0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
87c0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
87d0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
87e0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
87f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8800: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8810: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8820: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8840: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8850: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8860: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8870: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8880: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8890: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
88a0: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
88d0: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
88e0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
88f0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
8900: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8910: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8920: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
8930: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8940: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8950: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8960: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8970: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8980: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8990: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
89a0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
89b0: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
89c0: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
89d0: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
89e0: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
89f0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
8a00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8a10: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8a20: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8a30: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8a40: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8a50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8a60: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8a70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8a80: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8a90: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8aa0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8ab0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8ac0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8ad0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8ae0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8af0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8b00: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8b10: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8b20: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8b30: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8b40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8b50: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8b60: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8b70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8b80: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8b90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8ba0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8bb0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8bc0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8bd0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8be0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8bf0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8c00: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8c10: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
8c20: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
8c30: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
8c40: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
8c50: 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a  fined..** <ul>.*
8c60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8c70: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8c80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8c90: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8ca0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8cb0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8cc0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8cd0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8ce0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8cf0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8d00: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8d10: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8d20: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8d30: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8d40: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8d50: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8d60: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8d70: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8d80: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8d90: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8da0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8db0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8dc0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8dd0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8de0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8df0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8e00: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8e10: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8e20: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8e30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8e40: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8e50: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8e60: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8e70: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8e80: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8e90: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8ea0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8eb0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8ec0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8ed0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8ee0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
8ef0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
8f00: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
8f10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
8f20: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
8f30: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
8f40: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8f50: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8f60: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
8f70: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8f80: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8f90: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8fa0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8fb0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8fc0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8fd0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8fe0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8ff0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9000: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9010: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9020: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9030: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9040: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
9050: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9060: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9070: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9080: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9090: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
90a0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
90b0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
90c0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
90d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
90e0: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
90f0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9100: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
9110: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
9120: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9130: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9140: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9150: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9170: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9180: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9190: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
91a0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
91b0: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
91c0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
91d0: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
91e0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
91f0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9200: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9210: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
9220: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
9230: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9240: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9250: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9260: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9270: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9280: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9290: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
92a0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
92b0: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
92c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
92d0: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
92e0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
92f0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9300: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
9310: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9320: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
9330: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9340: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
9350: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
9360: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9370: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9380: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9390: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
93a0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
93b0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
93c0: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
93d0: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
93e0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
93f0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9400: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
9410: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9420: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9430: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9440: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9460: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9470: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9480: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9490: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
94a0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
94b0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
94c0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
94d0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
94e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
94f0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9500: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9510: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9520: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
9530: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9540: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
9550: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
9560: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9570: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9580: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9590: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
95a0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
95b0: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
95c0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
95d0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
95e0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
95f0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9600: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
9610: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
9620: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
9630: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9640: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9650: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9660: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9670: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9680: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9690: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
96a0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
96b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
96c0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
96d0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
96e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
96f0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9700: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9710: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9720: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9730: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9740: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9750: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9760: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9770: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9780: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9790: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
97a0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
97b0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
97c0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
97d0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
97e0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
97f0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9800: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9810: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9820: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9830: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9840: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9850: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9860: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9870: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9880: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9890: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
98a0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
98b0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
98c0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
98d0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
98e0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
98f0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9900: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9910: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9920: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9930: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9940: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9950: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9960: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9970: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9980: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9990: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
99a0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
99b0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
99c0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
99d0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
99e0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
99f0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9a00: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9a10: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9a20: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9a30: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9a40: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9a50: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9a60: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9a70: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9a80: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9a90: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9aa0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9ab0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9ac0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9ad0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9ae0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9af0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9b00: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9b10: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9b20: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9b30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9b40: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9b50: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9b60: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9b70: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9b80: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9b90: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9ba0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9bb0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9bc0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9bd0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9be0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9bf0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9c00: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9c10: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9c20: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9c30: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9c40: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9c50: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9c60: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9c70: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9c80: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9c90: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9ca0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9cb0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9cc0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9cd0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9ce0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9cf0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9d00: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9d10: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9d20: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9d30: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9d40: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9d50: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9d60: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9d70: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9d80: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9d90: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9da0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9db0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9dc0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9dd0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9de0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9df0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9e00: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9e10: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9e20: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9e30: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9e40: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9e50: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9e60: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9e70: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9e80: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9e90: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9ea0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9eb0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9ec0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ed0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9ee0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9ef0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9f00: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9f10: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9f20: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9f30: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9f40: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9f50: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9f60: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9f70: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
9f80: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
9f90: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
9fa0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
9fb0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
9fc0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
9fd0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9fe0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9ff0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a000: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a010: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a020: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a030: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a040: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a050: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a060: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a070: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a080: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a090: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a0a0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a0b0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a0c0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a0d0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a0e0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a0f0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a100: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a110: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a120: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a130: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a140: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a150: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a160: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a170: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a180: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a190: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a1a0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a1b0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a1c0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a1d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a1e0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a1f0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a200: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a210: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a220: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a230: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a240: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a250: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a260: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a270: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a280: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a290: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a2a0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a2b0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a2c0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a2d0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a2e0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a2f0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a300: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a310: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a320: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a330: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a340: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a350: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a360: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a370: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a380: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a390: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a3a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a3b0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a3c0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a3d0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a3e0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a3f0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a400: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a410: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a420: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a430: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a440: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a450: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a460: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a470: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a480: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a490: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a4a0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a4b0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a4c0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a4d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a4e0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a4f0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a500: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a510: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a520: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a530: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a540: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a550: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a560: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a570: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a580: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a590: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a5a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a5b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a5c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a5d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a5e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a5f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a600: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a610: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a620: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a630: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a640: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a650: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a660: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a670: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a680: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a690: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a6a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a6b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a6c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a6d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a6e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a6f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a700: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a710: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a720: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a730: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a740: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a750: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a760: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a770: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a780: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a790: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a7a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a7b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a7c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a7d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a7e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a7f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a800: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a810: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a820: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a830: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a840: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a850: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a860: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a870: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a880: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a890: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a8a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a8b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a8c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a8d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a8e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a8f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a900: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a910: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a920: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a930: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a940: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a950: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a960: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a970: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a980: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a990: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a9a0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a9b0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a9c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a9d0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a9e0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a9f0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
aa00: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
aa10: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
aa20: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
aa30: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
aa40: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
aa50: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
aa60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa70: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
aa80: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
aa90: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
aaa0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
aab0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
aac0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
aad0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
aae0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
aaf0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
ab00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ab10: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
ab20: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
ab30: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
ab40: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
ab50: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
ab60: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
ab70: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
ab80: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
ab90: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
aba0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
abb0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
abc0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
abd0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
abe0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
abf0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
ac00: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
ac10: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
ac20: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
ac30: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
ac40: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
ac50: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
ac60: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
ac70: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
ac80: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
ac90: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
aca0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
acb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
acc0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
acd0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
ace0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
acf0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
ad00: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
ad10: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
ad20: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
ad30: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
ad40: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
ad50: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
ad60: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
ad70: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
ad80: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
ad90: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
ada0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
adb0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
adc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
add0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
ade0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
adf0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ae00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ae10: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ae20: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
ae30: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
ae40: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
ae50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
ae60: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
ae70: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
ae80: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ae90: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
aea0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
aeb0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
aec0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
aed0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
aee0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
aef0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
af00: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
af10: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
af20: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
af30: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
af40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
af50: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
af60: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
af70: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
af80: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
af90: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
afa0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
afb0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
afc0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
afd0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
afe0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
aff0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b000: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
b010: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
b020: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b030: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
b040: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
b050: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
b060: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b070: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
b080: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
b090: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
b0a0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
b0b0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
b0c0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
b0d0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
b0e0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
b0f0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
b100: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
b110: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
b120: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
b130: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
b140: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
b150: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
b160: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
b170: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
b180: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
b190: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
b1a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
b1b0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
b1c0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
b1d0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
b1e0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
b1f0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
b200: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
b210: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b220: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
b230: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b240: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
b250: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
b260: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
b270: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
b280: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b290: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b2a0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b2b0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b2c0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b2d0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b2e0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b2f0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b300: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b310: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
b320: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
b330: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
b340: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
b350: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
b360: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
b370: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
b380: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
b390: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
b3a0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b3b0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
b3c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b3d0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b3e0: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
b3f0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b400: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
b410: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
b420: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
b430: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
b440: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
b450: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
b460: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
b470: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
b480: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
b490: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
b4a0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
b4b0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
b4c0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
b4d0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
b4e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b4f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
b500: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
b510: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b520: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
b530: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
b540: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
b550: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
b560: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
b570: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
b580: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
b590: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
b5a0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
b5b0: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
b5c0: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
b5d0: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
b5e0: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
b5f0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
b600: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
b610: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
b620: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
b630: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
b640: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b650: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
b660: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
b670: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
b680: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
b690: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
b6a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
b6b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
b6c0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
b6d0: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
b6e0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  O               
b6f0: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
b700: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
b710: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
b720: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
b730: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
b740: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
b750: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
b760: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
b770: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
b780: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
b790: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
b7a0: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
b7b0: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
b7c0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
b7d0: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
b7e0: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
b7f0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
b800: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
b810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b820: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
b830: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
b840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b850: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
b860: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
b870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b880: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
b890: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
b8a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b8b0: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
b8c0: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
b8d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b8e0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
b8f0: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
b900: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b910: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
b920: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
b930: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b940: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
b950: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
b960: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
b970: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
b980: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
b990: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
b9a0: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
b9b0: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
b9c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
b9d0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
b9e0: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
b9f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
ba00: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
ba10: 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51     22.#define SQ
ba20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
ba30: 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _SET_HANDLE     
ba40: 20 20 32 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    23../*.** CAPI
ba50: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
ba60: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
ba70: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
ba80: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
ba90: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
baa0: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
bab0: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
bac0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
bad0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
bae0: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
baf0: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
bb00: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
bb10: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
bb20: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
bb30: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
bb40: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
bb50: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
bb60: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
bb70: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
bb80: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
bb90: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
bba0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
bbb0: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
bbc0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
bbd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
bbe0: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
bbf0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
bc00: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
bc10: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
bc20: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
bc30: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
bc40: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
bc50: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
bc60: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
bc70: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
bc80: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
bc90: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
bca0: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
bcb0: 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65  le system".  See
bcc0: 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56  .** the [VFS | V
bcd0: 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  FS documentation
bce0: 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e  ] for further in
bcf0: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
bd00: 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   The value of th
bd10: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
bd20: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20   is initially 1 
bd30: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
bd40: 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76  r in.** future v
bd50: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
bd60: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
bd70: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
bd80: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
bd90: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
bda0: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
bdb0: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e  is increased.  N
bdc0: 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72  ote that the str
bdd0: 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65  ucture.** of the
bde0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
bdf0: 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74  ect changes in t
be00: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
be10: 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  etween.** SQLite
be20: 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61   version 3.5.9 a
be30: 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74  nd 3.6.0 and yet
be40: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
be50: 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d  eld was not.** m
be60: 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  odified..**.** T
be70: 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c  he szOsFile fiel
be80: 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  d is the size of
be90: 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20   the subclassed 
bea0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a  [sqlite3_file].*
beb0: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
bec0: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
bed0: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
bee0: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
bef0: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
bf00: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
bf10: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73  .** Registered s
bf20: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
bf30: 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61  ts are kept on a
bf40: 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72   linked list for
bf50: 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e  med by.** the pN
bf60: 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ext pointer.  Th
bf70: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  e [sqlite3_vfs_r
bf80: 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e  egister()].** an
bf90: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  d [sqlite3_vfs_u
bfa0: 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74  nregister()] int
bfb0: 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74  erfaces manage t
bfc0: 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61  his list.** in a
bfd0: 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79   thread-safe way
bfe0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
bff0: 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65  vfs_find()] inte
c000: 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65  rface.** searche
c010: 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69  s the list.  Nei
c020: 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  ther the applica
c030: 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68  tion code nor th
c040: 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65  e VFS.** impleme
c050: 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  ntation should u
c060: 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  se the pNext poi
c070: 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
c080: 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74  pNext field is t
c090: 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e  he only field in
c0a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c0b0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68  .** structure th
c0c0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  at SQLite will e
c0d0: 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c  ver modify.  SQL
c0e0: 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63  ite will only ac
c0f0: 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66  cess.** or modif
c100: 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69  y this field whi
c110: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
c120: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
c130: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
c140: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
c150: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
c160: 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65  thing within the
c170: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c180: 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20  object once the 
c190: 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20  object has been 
c1a0: 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a  registered..**.*
c1b0: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
c1c0: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
c1d0: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
c1e0: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
c1f0: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
c200: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
c210: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  odules..**.** [[
c220: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
c230: 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  n]].** ^SQLite g
c240: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
c250: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
c260: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
c270: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
c280: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
c290: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
c2a0: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
c2b0: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
c2c0: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
c2d0: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
c2e0: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
c2f0: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
c300: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
c310: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
c320: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
c330: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
c340: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
c350: 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65  .** 11 alphanume
c360: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
c370: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
c380: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
c390: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
c3a0: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
c3b0: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
c3c0: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
c3d0: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
c3e0: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
c3f0: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
c400: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
c410: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
c420: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
c430: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
c440: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
c450: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
c460: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
c470: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
c480: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
c490: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
c4a0: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
c4b0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
c4c0: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
c4d0: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
c4e0: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
c4f0: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
c500: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
c510: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c520: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
c530: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
c540: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
c550: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
c560: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
c570: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c580: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
c590: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
c5a0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
c5b0: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
c5c0: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
c5d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
c5e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
c5f0: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
c600: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
c610: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
c620: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
c630: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
c640: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
c650: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
c660: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
c670: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
c680: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
c690: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
c6a0: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
c6b0: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
c6c0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
c6d0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
c6e0: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
c6f0: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
c700: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
c710: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
c720: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
c730: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
c740: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
c750: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
c760: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
c770: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
c780: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
c790: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
c7a0: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
c7b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
c7c0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
c7d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c7e0: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
c7f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
c800: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
c810: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c820: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
c830: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c840: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
c850: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
c860: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
c870: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
c880: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
c890: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
c8a0: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
c8b0: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
c8c0: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
c8d0: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
c8e0: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
c8f0: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
c900: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
c910: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
c920: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
c930: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
c940: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
c950: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
c960: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
c970: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
c980: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
c990: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
c9a0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
c9b0: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
c9c0: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
c9d0: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
c9e0: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
c9f0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
ca00: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
ca10: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
ca20: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
ca30: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
ca40: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
ca50: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
ca60: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
ca70: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
ca80: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
ca90: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
caa0: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
cab0: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
cac0: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
cad0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
cae0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
caf0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
cb00: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
cb10: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
cb20: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
cb30: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
cb40: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
cb50: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
cb60: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
cb70: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
cb80: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
cb90: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
cba0: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
cbb0: 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
cbc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
cbd0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
cbe0: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
cbf0: 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
cc00: 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
cc10: 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
cc20: 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
cc30: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
cc40: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
cc50: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
cc60: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
cc70: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
cc80: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
cc90: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
cca0: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
ccb0: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
ccc0: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
ccd0: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
cce0: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
ccf0: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
cd00: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
cd10: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
cd20: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
cd30: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
cd40: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
cd50: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
cd60: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
cd70: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
cd80: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
cd90: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
cda0: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
cdb0: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
cdc0: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
cdd0: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
cde0: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
cdf0: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
ce00: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
ce10: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
ce20: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
ce30: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
ce40: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
ce50: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
ce60: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
ce70: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
ce80: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
ce90: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
cea0: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
ceb0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
cec0: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
ced0: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
cee0: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
cef0: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
cf00: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
cf10: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
cf20: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
cf30: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
cf40: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
cf50: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
cf60: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
cf70: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
cf80: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
cf90: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
cfa0: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
cfb0: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
cfc0: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
cfd0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
cfe0: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
cff0: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
d000: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
d010: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
d020: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
d030: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
d040: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
d050: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41  [[sqlite3_vfs.xA
d060: 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20  ccess]].** ^The 
d070: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
d080: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
d090: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
d0a0: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
d0b0: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
d0c0: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
d0d0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
d0e0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
d0f0: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
d100: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
d110: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
d120: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
d130: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
d140: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d150: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
d160: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
d170: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
d180: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
d190: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
d1a0: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
d1b0: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
d1c0: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
d1d0: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
d1e0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
d1f0: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
d200: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
d210: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
d220: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
d230: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
d240: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
d250: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
d260: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
d270: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
d280: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
d290: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
d2a0: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
d2b0: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
d2c0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
d2d0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
d2e0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
d2f0: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
d300: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
d310: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
d320: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
d330: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
d340: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
d350: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
d360: 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  ), xCurrentTime(
d370: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
d380: 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e  imeInt64().** in
d390: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74  terfaces are not
d3a0: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
d3b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
d3c0: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
d3d0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
d3e0: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
d3f0: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
d400: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
d410: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
d420: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
d430: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
d440: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
d450: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
d460: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
d470: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
d480: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
d490: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
d4a0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
d4b0: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
d4c0: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
d4d0: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
d4e0: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
d4f0: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
d500: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
d510: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
d520: 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  .  ^The xCurrent
d530: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
d540: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
d550: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
d560: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
d570: 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a  e and time as.**
d580: 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
d590: 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65  t value..** ^The
d5a0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d5b0: 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  64() method retu
d5c0: 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67  rns, as an integ
d5d0: 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a  er, the Julian.*
d5e0: 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c  * Day Number mul
d5f0: 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30  tiplied by 86400
d600: 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20  000 (the number 
d610: 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
d620: 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72  in .** a 24-hour
d630: 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c   day).  .** ^SQL
d640: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
d650: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d660: 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67  64() method to g
d670: 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  et the current.*
d680: 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  * date and time 
d690: 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69  if that method i
d6a0: 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20  s available (if 
d6b0: 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72  iVersion is 2 or
d6c0: 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64   .** greater and
d6d0: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
d6e0: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
d6f0: 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c  L) and will fall
d700: 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72   back.** to xCur
d710: 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43  rentTime() if xC
d720: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d730: 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  ) is unavailable
d740: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65  ..**.** ^The xSe
d750: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78  tSystemCall(), x
d760: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  GetSystemCall(),
d770: 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d   and xNestSystem
d780: 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  Call() interface
d790: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65  s.** are not use
d7a0: 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20  d by the SQLite 
d7b0: 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74  core.  These opt
d7c0: 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ional interfaces
d7d0: 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a   are provided.**
d7e0: 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74   by some VFSes t
d7f0: 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73  o facilitate tes
d800: 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20  ting of the VFS 
d810: 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64  code. By overrid
d820: 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63  ing .** system c
d830: 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69  alls with functi
d840: 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f  ons under its co
d850: 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72  ntrol, a test pr
d860: 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d  ogram can.** sim
d870: 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64  ulate faults and
d880: 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e   error condition
d890: 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68  s that would oth
d8a0: 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63  erwise be diffic
d8b0: 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73  ult.** or imposs
d8c0: 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20  ible to induce. 
d8d0: 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74   The set of syst
d8e0: 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61  em calls that ca
d8f0: 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a  n be overridden.
d900: 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f  ** varies from o
d910: 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65  ne VFS to anothe
d920: 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20  r, and from one 
d930: 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73  version of the s
d940: 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a  ame VFS to the.*
d950: 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
d960: 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74  tions that use t
d970: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
d980: 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64  must be prepared
d990: 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61   for any.** or a
d9a0: 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ll of these inte
d9b0: 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c  rfaces to be NUL
d9c0: 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62  L or for their b
d9d0: 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67  ehavior to chang
d9e0: 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65  e.** from one re
d9f0: 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78  lease to the nex
da00: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
da10: 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70   must not attemp
da20: 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61  t to access.** a
da30: 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68  ny of these meth
da40: 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73  ods if the iVers
da50: 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69  ion of the VFS i
da60: 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a  s less than 3..*
da70: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
da80: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
da90: 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65  ite3_vfs;.typede
daa0: 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
dab0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f  _syscall_ptr)(vo
dac0: 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  id);.struct sqli
dad0: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
dae0: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
daf0: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
db00: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
db10: 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a   (currently 3) *
db20: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
db30: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
db40: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
db50: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
db60: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
db70: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
db80: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
db90: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
dba0: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
dbb0: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
dbc0: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
dbd0: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
dbe0: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
dbf0: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
dc00: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
dc10: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
dc20: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
dc30: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
dc40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
dc50: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
dc60: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
dc70: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dc80: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
dc90: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
dca0: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
dcb0: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
dcc0: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
dcd0: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
dce0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
dcf0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
dd00: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
dd10: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
dd20: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
dd30: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
dd40: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
dd50: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
dd60: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
dd70: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
dd80: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
dd90: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
dda0: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
ddb0: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
ddc0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ddd0: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
dde0: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
ddf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
de00: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
de10: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28  rrMsg);.  void (
de20: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
de30: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
de40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
de50: 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f  ol))(void);.  vo
de60: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
de70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
de80: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
de90: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
dea0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
deb0: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
dec0: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
ded0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
dee0: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
def0: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
df00: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
df10: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
df20: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
df30: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
df40: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
df50: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
df60: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
df70: 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f  e in version 1 o
df80: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
df90: 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66   object.  ** def
dfa0: 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20  inition.  Those 
dfb0: 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20  that follow are 
dfc0: 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e  added in version
dfd0: 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f   2 or later.  */
dfe0: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
dff0: 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69  tTimeInt64)(sqli
e000: 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65  te3_vfs*, sqlite
e010: 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a  3_int64*);.  /*.
e020: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
e030: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
e040: 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f  rsions 1 and 2 o
e050: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
e060: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68   object..  ** Th
e070: 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f  ose below are fo
e080: 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20  r version 3 and 
e090: 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20  greater..  */.  
e0a0: 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d  int (*xSetSystem
e0b0: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
e0c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e0d0: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
e0e0: 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73  yscall_ptr);.  s
e0f0: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
e100: 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43  tr (*xGetSystemC
e110: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
e120: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e130: 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63  Name);.  const c
e140: 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74  har *(*xNextSyst
e150: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e160: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e170: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20   *zName);.  /*. 
e180: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
e190: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
e1a0: 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20  sions 1 through 
e1b0: 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  3 of the sqlite_
e1c0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
e1d0: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
e1e0: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
e1f0: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
e200: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
e210: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
e220: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
e230: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a   this happens. .
e240: 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43    */.};../*.** C
e250: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e260: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
e270: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
e280: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
e290: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
e2a0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
e2b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
e2c0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e2d0: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
e2e0: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
e2f0: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
e300: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
e310: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
e320: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
e330: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
e340: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
e350: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
e360: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e370: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
e380: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
e390: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
e3a0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e3b0: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
e3c0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
e3d0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
e3e0: 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74  the named direct
e3f0: 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64  ory is both read
e400: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
e410: 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77  e.** (in other w
e420: 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63  ords, if files c
e430: 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d  an be added, rem
e440: 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65  oved, and rename
e450: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
e460: 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54  directory)..** T
e470: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
e480: 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74  _READWRITE const
e490: 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ant is currently
e4a0: 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68   used only by th
e4b0: 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65  e.** [temp_store
e4c0: 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
e4d0: 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20  a], though this 
e4e0: 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20  could change in 
e4f0: 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
e500: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
e510: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
e520: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
e530: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
e540: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
e550: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
e560: 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54  able.  The SQLIT
e570: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f  E_ACCESS_READ co
e580: 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72  nstant is.** cur
e590: 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74  rently unused, t
e5a0: 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62  hough it might b
e5b0: 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75  e used in a futu
e5c0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
e5d0: 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
e5e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
e5f0: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
e600: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e610: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20  ESS_READWRITE 1 
e620: 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41    /* Used by PRA
e630: 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64  GMA temp_store_d
e640: 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66  irectory */.#def
e650: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
e660: 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20  S_READ      2   
e670: 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a  /* Unused */../*
e680: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
e690: 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d  ags for the xShm
e6a0: 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a  Lock VFS method.
e6b0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
e6c0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ger constants de
e6d0: 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73  fine the various
e6e0: 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69   locking operati
e6f0: 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62  ons.** allowed b
e700: 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  y the xShmLock m
e710: 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65  ethod of [sqlite
e720: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20  3_io_methods].  
e730: 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  The.** following
e740: 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65   are the only le
e750: 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  gal combinations
e760: 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65   of flags to the
e770: 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  .** xShmLock met
e780: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
e790: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
e7a0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
e7b0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
e7c0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e7d0: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
e7e0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
e7f0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e800: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
e810: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
e820: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
e830: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
e840: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
e850: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65   </ul>.**.** Whe
e860: 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65  n unlocking, the
e870: 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20   same SHARED or 
e880: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d  EXCLUSIVE flag m
e890: 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20  ust be supplied 
e8a0: 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20  as.** was given 
e8b0: 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  on the correspon
e8c0: 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a  ding lock.  .**.
e8d0: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
e8e0: 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73  method can trans
e8f0: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e  ition between un
e900: 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45  locked and SHARE
e910: 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20  D or.** between 
e920: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43  unlocked and EXC
e930: 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e  LUSIVE.  It cann
e940: 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  ot transition be
e950: 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20  tween SHARED.** 
e960: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a  and EXCLUSIVE..*
e970: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e980: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  _SHM_UNLOCK     
e990: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
e9a0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20  TE_SHM_LOCK     
e9b0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
e9c0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20  LITE_SHM_SHARED 
e9d0: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
e9e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
e9f0: 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a  SIVE    8../*.**
ea00: 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d   CAPI3REF: Maxim
ea10: 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65  um xShmLock inde
ea20: 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d  x.**.** The xShm
ea30: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b  Lock method on [
ea40: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ea50: 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75  ds] may use valu
ea60: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  es.** between 0 
ea70: 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62  and this upper b
ea80: 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66  ound as its "off
ea90: 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  set" argument..*
eaa0: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
eab0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74  e will never att
eac0: 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20  empt to acquire 
ead0: 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20  or release a.** 
eae0: 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20  lock outside of 
eaf0: 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64  this range.*/.#d
eb00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
eb10: 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a  _NLOCK        8.
eb20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
eb30: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
eb40: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
eb50: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
eb60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
eb70: 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69  routine initiali
eb80: 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  zes the.** SQLit
eb90: 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65  e library.  ^The
eba0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
ebb0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
ebc0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
ebd0: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
ebe0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
ebf0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ec00: 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ze()..** These r
ec10: 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69  outines are desi
ec20: 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70  gned to aid in p
ec30: 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
ec40: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75  ation and.** shu
ec50: 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65  tdown on embedde
ec60: 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b  d systems.  Work
ec70: 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74  station applicat
ec80: 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ions using.** SQ
ec90: 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f  Lite normally do
eca0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76   not need to inv
ecb0: 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68  oke either of th
ecc0: 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
ecd0: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
ece0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ecf0: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
ed00: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
ed10: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
ed20: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
ed30: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
ed40: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
ed50: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
ed60: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
ed70: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
ed80: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
ed90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
eda0: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
edb0: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
edc0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
edd0: 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66  .  ^(Only an eff
ede0: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
edf0: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
ee00: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
ee10: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
ee20: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
ee30: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
ee40: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
ee50: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
ee60: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73  e3_shutdown() is
ee70: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
ee80: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68  call if it is th
ee90: 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20  e first.** call 
eea0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
eeb0: 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20  own() since the 
eec0: 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  last sqlite3_ini
eed0: 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e  tialize().  ^(On
eee0: 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
eef0: 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
ef00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
ef10: 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
ef20: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
ef30: 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
ef40: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
ef50: 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
ef60: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
ef70: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
ef80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e  _initialize() in
ef90: 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61  terface is threa
efa0: 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74  dsafe, but sqlit
efb0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
efc0: 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71   is not.  The sq
efd0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
efe0: 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20   interface must 
eff0: 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66  only be called f
f000: 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  rom a.** single 
f010: 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65  thread.  All ope
f020: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
f030: 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65  ections] must be
f040: 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a   closed and all.
f050: 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
f060: 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62  resources must b
f070: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72  e deallocated pr
f080: 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a  ior to invoking.
f090: 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ** sqlite3_shutd
f0a0: 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  own()..**.** Amo
f0b0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
f0c0: 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   ^sqlite3_initia
f0d0: 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f  lize() will invo
f0e0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
f0f0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
f100: 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68  rly, ^sqlite3_sh
f110: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c  utdown().** will
f120: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f130: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
f140: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f150: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f160: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
f170: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
f180: 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d  ..** ^If for som
f190: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65  e reason, sqlite
f1a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f1b0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74  s unable to init
f1c0: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69  ialize.** the li
f1d0: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69  brary (perhaps i
f1e0: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  t is unable to a
f1f0: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64  llocate a needed
f200: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a   resource such.*
f210: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74  * as a mutex) it
f220: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72   returns an [err
f230: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74  or code] other t
f240: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  han [SQLITE_OK].
f250: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f260: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f270: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
f280: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
f290: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
f2a0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
f2b0: 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
f2c0: 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
f2d0: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
f2e0: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
f2f0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f300: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
f310: 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
f320: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
f330: 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
f340: 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
f350: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
f360: 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
f370: 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
f380: 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
f390: 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
f3a0: 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
f3b0: 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
f3c0: 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77  * already.  ^How
f3d0: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
f3e0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f3f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
f400: 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
f410: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
f420: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
f430: 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
f440: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f450: 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
f460: 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
f470: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
f480: 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
f490: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
f4a0: 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
f4b0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
f4c0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
f4d0: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
f4e0: 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
f4f0: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
f500: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
f510: 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
f520: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f530: 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
f540: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
f550: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
f560: 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
f570: 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
f580: 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
f590: 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
f5a0: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
f5b0: 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
f5c0: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
f5d0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f5e0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
f5f0: 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
f600: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
f610: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
f620: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
f630: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
f640: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
f650: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
f660: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
f670: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
f680: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
f690: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
f6a0: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
f6b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f6c0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
f6d0: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
f6e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f6f0: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
f700: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
f710: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
f720: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
f730: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
f740: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
f750: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
f760: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
f770: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
f780: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
f790: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
f7a0: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
f7b0: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
f7c0: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
f7d0: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
f7e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f7f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
f800: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
f810: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
f820: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
f830: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
f840: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
f850: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
f860: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
f870: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
f880: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f890: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
f8a0: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
f8b0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f8c0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
f8d0: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
f8e0: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
f8f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
f900: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
f910: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
f920: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
f930: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
f940: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
f950: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
f960: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
f970: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f980: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
f990: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
f9a0: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
f9b0: 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73  or Unix, Windows
f9c0: 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68  , or OS/2..** Wh
f9d0: 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64  en [custom build
f9e0: 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  s | built for ot
f9f0: 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a  her platforms].*
fa00: 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  * (using the [SQ
fa10: 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
fa20: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
fa30: 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
fa40: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
fa50: 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
fa60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
fa70: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
fa80: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
fa90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
faa0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
fab0: 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
fac0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
fad0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
fae0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
faf0: 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
fb00: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
fb10: 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
fb20: 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
fb30: 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
fb40: 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ure..*/.int sqli
fb50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
fb60: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
fb70: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
fb80: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
fb90: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74  _init(void);.int
fba0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fbb0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
fbc0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
fbd0: 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
fbe0: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
fbf0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
fc00: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
fc10: 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
fc20: 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
fc30: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
fc40: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
fc50: 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
fc60: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
fc70: 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
fc80: 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
fc90: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
fca0: 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
fcb0: 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
fcc0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
fcd0: 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
fce0: 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
fcf0: 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
fd00: 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
fd10: 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
fd20: 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
fd30: 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
fd40: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fd50: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
fd60: 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
fd70: 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
fd80: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
fd90: 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
fda0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
fdb0: 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
fdc0: 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
fdd0: 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
fde0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fdf0: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
fe00: 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
fe10: 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
fe20: 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
fe30: 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
fe40: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
fe50: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
fe60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
fe70: 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
fe80: 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
fe90: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
fea0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
feb0: 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
fec0: 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
fed0: 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
fee0: 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
fef0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
ff00: 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
ff10: 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
ff20: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
ff30: 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
ff40: 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
ff50: 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
ff60: 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
ff70: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
ff80: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
ff90: 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
ffa0: 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
ffb0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ffc0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
ffd0: 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
ffe0: 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
fff0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
10000 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
10010 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
10020 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
10030 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
10040 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
10050 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
10060 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
10070 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10080 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
10090 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
100a0 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
100b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
100c0 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
100d0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
100e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
100f0 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
10100 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
10110 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
10120 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
10130 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
10140 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
10150 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
10160 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  code]..*/.int sq
10170 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
10180 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
10190 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
101a0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
101b0 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  ections.**.** Th
101c0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
101d0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
101e0 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
101f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10200 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
10210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10220 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
10230 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
10240 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10250 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
10260 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
10270 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
10280 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
10290 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
102a0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
102b0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
102c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
102d0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
102e0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
102f0 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
10300 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
10310 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
10320 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10330 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
10340 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
10350 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
10360 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
10370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10380 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
10390 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
103a0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
103b0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
103c0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
103d0 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
103e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
103f0 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
10400 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
10410 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
10420 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
10430 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
10440 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10450 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
10460 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
10470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10480 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
10490 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
104a0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
104b0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
104c0 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
104d0 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
104e0 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
104f0 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
10500 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
10510 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
10520 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
10530 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
10540 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
10550 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
10560 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
10570 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10580 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
10590 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
105a0 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
105b0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
105c0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
105d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
105e0 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
105f0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
10600 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
10610 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
10620 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
10630 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
10640 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
10650 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
10660 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
10670 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
10680 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
10690 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
106a0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
106b0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
106c0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
106d0 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
106e0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
106f0 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
10700 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
10710 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
10720 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
10730 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
10740 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
10750 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
10760 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
10770 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
10780 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
10790 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
107a0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
107b0 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
107c0 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
107d0 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
107e0 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
107f0 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
10800 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10810 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
10820 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
10830 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
10840 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
10850 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
10860 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
10870 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
10880 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
10890 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
108a0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
108b0 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
108c0 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
108d0 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
108e0 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
108f0 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
10900 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
10910 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
10920 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
10930 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
10940 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
10950 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
10960 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
10970 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
10980 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
10990 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
109a0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
109b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
109c0 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
109d0 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
109e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
109f0 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
10a00 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
10a10 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
10a20 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
10a30 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
10a40 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
10a50 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
10a60 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
10a70 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
10a80 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
10a90 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
10aa0 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
10ab0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
10ac0 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
10ad0 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
10ae0 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
10af0 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
10b00 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
10b10 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
10b20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10b30 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
10b40 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
10b50 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
10b60 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
10b70 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
10b80 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
10b90 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
10ba0 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
10bb0 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
10bc0 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
10bd0 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
10be0 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
10bf0 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
10c00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10c10 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
10c20 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
10c30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
10c40 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
10c50 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
10c60 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
10c70 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
10c80 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
10c90 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
10ca0 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
10cb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
10cc0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
10cd0 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
10ce0 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
10cf0 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f  y allocator.  Fo
10d00 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
10d10 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
10d20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
10d30 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
10d40 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
10d50 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
10d60 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
10d70 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
10d80 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
10d90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
10da0 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
10db0 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
10dc0 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
10dd0 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
10de0 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
10df0 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
10e00 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
10e10 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
10e20 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
10e30 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
10e40 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
10e50 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
10e60 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
10e70 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
10e80 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
10e90 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
10ea0 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
10eb0 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
10ec0 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
10ed0 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
10ee0 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
10ef0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
10f00 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
10f10 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
10f20 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
10f30 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
10f40 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
10f50 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
10f60 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
10f70 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
10f80 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
10f90 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
10fa0 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
10fb0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
10fc0 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
10fd0 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
10fe0 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
10ff0 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
11000 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
11010 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
11020 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
11030 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
11040 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
11050 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
11060 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
11070 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
11080 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
11090 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
110a0 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
110b0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
110c0 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
110d0 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
110e0 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
110f0 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
11100 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
11110 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
11120 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
11130 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
11140 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11150 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
11160 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
11170 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
11180 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11190 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
111a0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
111b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
111c0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
111d0 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
111e0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
111f0 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
11200 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
11210 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
11220 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11230 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
11240 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
11250 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
11260 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
11270 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
11280 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
11290 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
112a0 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
112b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
112c0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
112d0 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
112e0 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
112f0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
11300 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
11310 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
11320 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
11330 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
11340 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11350 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
11360 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
11370 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
11380 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
11390 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
113a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
113b0 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
113c0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
113d0 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
113e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
113f0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
11400 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
11410 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
11420 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11430 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
11440 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
11450 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
11460 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
11470 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
11480 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
11490 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
114a0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
114b0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
114c0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
114d0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
114e0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
114f0 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
11500 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
11510 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
11520 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
11530 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
11540 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
11550 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
11560 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
11570 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
11580 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
11590 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
115a0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
115b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
115c0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
115d0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
115e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
115f0 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
11600 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
11610 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11620 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
11630 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11640 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
11650 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
11660 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
11670 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
11680 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
11690 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
116a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
116b0 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
116c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
116d0 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
116e0 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
116f0 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
11700 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
11710 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
11720 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
11730 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
11740 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11750 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11760 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11770 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11780 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11790 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
117a0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
117b0 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
117c0 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
117d0 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
117e0 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
117f0 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
11800 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
11810 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
11820 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
11830 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
11840 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
11850 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11860 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
11870 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
11880 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11890 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
118a0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
118b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
118c0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
118d0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
118e0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
118f0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11900 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11910 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
11920 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
11930 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
11940 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
11950 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
11960 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
11970 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
11980 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11990 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
119a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
119b0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
119c0 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
119d0 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
119e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
119f0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11a00 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
11a10 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
11a20 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
11a30 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
11a40 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
11a50 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
11a60 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
11a70 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
11a80 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
11a90 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
11aa0 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
11ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
11ac0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
11ad0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11ae0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11af0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11b00 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11b10 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11b20 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11b30 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
11b40 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
11b50 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
11b60 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
11b70 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
11b80 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11b90 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
11ba0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11bb0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
11bc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
11bd0 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
11be0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
11bf0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11c00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
11c10 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
11c20 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11c30 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
11c40 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
11c50 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
11c60 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
11c70 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
11c80 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
11c90 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
11ca0 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
11cb0 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
11cc0 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
11cd0 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
11ce0 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
11cf0 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
11d00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11d10 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11d20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
11d30 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
11d40 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
11d50 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
11d60 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11d70 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
11d80 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
11d90 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11da0 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
11db0 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
11dc0 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
11dd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
11de0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11df0 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
11e00 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
11e10 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
11e20 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
11e30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11e40 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
11e50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11e60 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
11e70 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
11e80 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
11e90 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11ea0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11eb0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11ec0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11ed0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11ee0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11ef0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11f00 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
11f10 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
11f20 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11f30 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
11f40 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11f50 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11f60 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11f70 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
11f80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11f90 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
11fa0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11fb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11fc0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
11fd0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11fe0 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
11ff0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
12000 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12010 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12020 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12030 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
12040 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
12050 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
12060 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12070 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
12080 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
12090 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
120a0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
120b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
120c0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
120d0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
120e0 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
120f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12100 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
12110 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
12120 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
12130 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
12140 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
12150 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12160 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12170 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
12180 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
12190 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
121a0 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
121b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
121c0 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
121d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
121e0 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
121f0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
12200 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12210 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
12220 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12230 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
12240 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12250 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12260 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12270 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12280 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
12290 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
122a0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
122b0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
122c0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
122d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
122e0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
122f0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
12300 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
12310 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
12320 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12330 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
12340 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
12350 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
12360 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12370 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
12380 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
12390 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
123a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
123b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
123c0 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
123d0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
123e0 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
123f0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
12400 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74  IG_MEMSTATUS opt
12410 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
12420 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
12430 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70  e int,.** interp
12440 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
12450 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
12460 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
12470 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a  e collection of.
12480 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
12490 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e  tion statistics.
124a0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
124b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
124c0 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  tics are.** disa
124d0 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
124e0 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
124f0 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
12500 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
12510 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
12520 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12530 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
12540 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
12550 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
12560 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12570 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
12580 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
12590 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
125a0 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
125b0 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
125c0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
125d0 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
125e0 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
125f0 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
12600 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
12610 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
12620 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
12630 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
12640 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
12650 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
12660 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
12670 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
12680 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12690 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
126a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
126b0 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
126c0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
126d0 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69  FIG_SCRATCH opti
126e0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
126f0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12700 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
12710 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73  te can use for s
12720 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
12730 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65  ^(There are thre
12740 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74  e arguments.** t
12750 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
12760 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e  SCRATCH:  A poin
12770 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
12780 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
12790 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
127a0 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
127b0 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
127c0 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
127d0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
127e0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
127f0 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
12800 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
12810 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
12820 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a  ations (N).)^.**
12830 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12840 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
12850 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
12860 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
12870 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
12880 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
12890 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
128a0 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d  e will not use m
128b0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
128c0 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
128d0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c   thread..** ^SQL
128e0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
128f0 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68  equest a scratch
12900 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
12910 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
12920 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
12930 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
12940 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
12950 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
12960 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
12970 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
12980 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
12990 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
129a0 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
129b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
129c0 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
129d0 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
129e0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
129f0 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  p>.** ^When the 
12a00 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76  application prov
12a10 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20  ides any amount 
12a20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  of scratch memor
12a30 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  y using.** SQLIT
12a40 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12a50 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20  , SQLite avoids 
12a60 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67  unnecessary larg
12a70 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
12a80 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61  lloc|heap alloca
12a90 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20  tions]..** This 
12aa0 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e  can help [Robson
12ab0 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d   proof|prevent m
12ac0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12ad0 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74   failures] due t
12ae0 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65  o heap.** fragme
12af0 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d  ntation in low-m
12b00 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73  emory embedded s
12b10 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  ystems..** </dd>
12b20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12b30 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
12b40 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12b50 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
12b60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
12b70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
12b80 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
12b90 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12ba0 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12bb0 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
12bc0 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20  can use for the 
12bd0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
12be0 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
12bf0 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63  ault page.** cac
12c00 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12c10 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
12c20 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
12c30 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
12c40 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
12c50 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
12c60 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12c70 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
12c80 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
12c90 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a  CONFIG_PCACHE2].
12ca0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12cb0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65   option..** ^The
12cc0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
12cd0 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
12ce0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12cf0 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
12d00 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
12d10 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
12d20 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
12d30 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
12d40 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
12d50 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
12d60 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
12d70 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
12d80 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
12d90 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
12da0 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
12db0 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
12dc0 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
12dd0 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
12de0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
12df0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
12e00 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
12e10 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
12e20 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
12e30 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
12e40 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ned using the [S
12e50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
12e60 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f  CHE_HDRSZ] optio
12e70 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  n .** to [sqlite
12e80 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20  3_config()]..** 
12e90 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
12ea0 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
12eb0 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
12ec0 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
12ed0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
12ee0 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
12ef0 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
12f00 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
12f10 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  d pointer to an 
12f20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
12f30 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74  lock of memory t
12f40 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61  hat.** is at lea
12f50 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
12f60 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69   memory, otherwi
12f70 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  se subsequent be
12f80 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
12f90 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69  efined..** ^SQLi
12fa0 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
12fb0 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
12fc0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
12fd0 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
12fe0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
12ff0 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
13000 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
13010 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
13020 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
13030 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
13040 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
13050 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
13060 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
13070 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
13080 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
13090 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
130a0 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
130b0 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
130c0 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ace.</dd>.**.** 
130d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
130e0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
130f0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
13100 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
13120 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
13130 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
13140 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
13150 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
13160 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
13170 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
13180 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13190 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
131a0 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
131b0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
131c0 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a  G_SCRATCH] and.*
131d0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
131e0 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
131f0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13200 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69  IG_HEAP option i
13210 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
13220 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
13230 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65  mpiled.** with e
13240 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
13250 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
13260 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
13270 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74  MEMSYS5] and ret
13280 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
13290 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65  ERROR] if invoke
132a0 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20  d otherwise..** 
132b0 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
132c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
132d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
132e0 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61  :.** An 8-byte a
132f0 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
13300 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
13310 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
13320 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
13330 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
13340 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13350 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
13360 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
13370 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13380 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
13390 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
133a0 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
133b0 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
133c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
133d0 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
133e0 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
133f0 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
13400 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
13410 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
13420 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
13430 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
13440 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
13450 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  ot NULL then the
13460 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
13470 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
13480 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
13490 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
134a0 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
134b0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
134c0 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
134d0 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
134e0 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
134f0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
13500 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
13510 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
13520 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
13530 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
13540 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
13550 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13560 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
13570 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
13580 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
13590 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
135a0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
135b0 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
135c0 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
135d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
135e0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
135f0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
13600 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13610 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13620 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
13630 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13640 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a  ment which is a.
13650 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
13660 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13670 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13680 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13690 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
136a0 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c  ent specifies al
136b0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
136c0 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
136d0 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a  es to be used.**
136e0 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75   in place the mu
136f0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
13700 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
13710 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
13720 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
13730 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
13740 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13750 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13760 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
13770 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
13780 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
13790 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
137a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
137b0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
137c0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
137d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
137e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
137f0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13800 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13810 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13820 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
13830 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
13840 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
13850 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13860 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
13870 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
13880 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13890 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
138a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
138b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
138c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
138d0 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
138e0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
138f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13900 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13910 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f  G_GETMUTEX optio
13920 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13930 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
13940 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
13950 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
13960 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13970 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
13980 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
13990 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
139a0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
139b0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
139c0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
139d0 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
139e0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
139f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
13a00 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
13a10 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
13a20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
13a30 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
13a40 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
13a50 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
13a60 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
13a70 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
13a80 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
13a90 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
13aa0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13ab0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13ac0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13ad0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13ae0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13af0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13b00 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
13b10 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
13b20 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
13b30 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
13b40 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
13b50 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13b60 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
13b70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13b80 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
13b90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
13ba0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
13bb0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
13bc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13bd0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13be0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13bf0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
13c00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13c10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13c20 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e  LOOKASIDE option
13c30 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
13c40 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
13c50 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75  ine.** the defau
13c60 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61  lt size of looka
13c70 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65  side memory on e
13c80 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
13c90 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
13ca0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13cb0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
13cc0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
13cd0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
13ce0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
13cf0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
13d00 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
13d10 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
13d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
13d30 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   ^(SQLITE_CONFIG
13d40 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65  _LOOKASIDE.** se
13d50 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c  ts the <i>defaul
13d60 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
13d70 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
13d80 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
13d90 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20  SIDE].** option 
13da0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
13db0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
13dc0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
13dd0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
13de0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
13df0 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
13e00 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
13e10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13e20 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
13e30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13e40 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
13e50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13e70 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
13e80 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13e90 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
13ea0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13eb0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
13ec0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
13ed0 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
13ee0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
13ef0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63  interface to a c
13f00 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
13f10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13f20 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61  )^.** ^SQLite ma
13f30 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
13f40 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  e [sqlite3_pcach
13f50 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
13f60 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ct.</dd>.**.** [
13f70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
13f80 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
13f90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13fa0 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
13fb0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
13fc0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13fd0 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
13fe0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13ff0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
14000 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14010 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
14020 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
14030 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
14040 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65   of.** the curre
14050 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  nt page cache im
14060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
14070 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
14080 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
140a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
140b0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
140c0 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
140d0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
140e0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
140f0 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
14100 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
14110 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
14120 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14130 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
14140 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
14150 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
14160 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
14170 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
14180 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
14190 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
141a0 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
141b0 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
141c0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
141d0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
141e0 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
141f0 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
14200 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
14210 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
14220 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
14230 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
14240 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
14250 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
14260 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
14270 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
14280 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
14290 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
142a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
142b0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
142c0 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
142d0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
142e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
142f0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
14300 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
14310 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
14320 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
14330 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
14340 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
14350 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
14360 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
14370 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
14380 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14390 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
143a0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
143b0 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
143c0 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
143d0 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
143e0 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
143f0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
14400 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
14410 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
14420 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
14430 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
14440 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
14450 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
14460 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
14470 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
14480 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
14490 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
144a0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
144b0 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
144c0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
144d0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
144e0 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
144f0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
14500 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
14510 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
14520 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14530 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14540 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
14550 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
14560 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14570 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
14580 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14590 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
145a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
145b0 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  URI option takes
145c0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
145d0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a  nt of type int..
145e0 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  ** If non-zero, 
145f0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
14600 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
14610 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
14620 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
14630 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e  .** then URI han
14640 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14650 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
14660 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
14670 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e  s globally.** en
14680 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
14690 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b  ames passed to [
146a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
146b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
146c0 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
146d0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
146e0 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
146f0 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
14700 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
14710 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14720 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
14730 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
14740 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
14750 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
14760 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
14770 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
14780 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14790 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
147a0 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
147b0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
147c0 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
147d0 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
147e0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
147f0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14800 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
14810 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
14820 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
14830 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
14840 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
14850 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
14860 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
14870 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
14880 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
14890 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
148a0 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
148b0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
148c0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
148d0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
148e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
148f0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
14900 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
14910 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14920 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14930 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SCAN option take
14940 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
14950 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77  er.** argument w
14960 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
14970 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
14980 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
14990 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a  ble or disable.*
149a0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  * the use of cov
149b0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
149c0 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
149d0 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
149e0 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54  optimizer..** ^T
149f0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
14a00 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
14a10 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
14a20 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
14a30 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
14a40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14a50 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
14a60 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
14a70 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
14a80 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
14a90 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
14aa0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
14ab0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
14ac0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
14ad0 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
14ae0 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
14af0 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
14b00 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
14b10 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
14b20 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
14b30 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
14b40 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
14b50 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
14b60 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
14b70 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
14b80 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
14b90 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
14ba0 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
14bb0 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
14bc0 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
14bd0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
14be0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14bf0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
14c00 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14c10 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
14c20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14c30 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
14c40 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14c50 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
14c60 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
14c70 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
14c80 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
14c90 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
14ca0 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
14cb0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
14cc0 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
14cd0 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
14ce0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
14cf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
14d00 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
14d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
14d20 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
14d30 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
14d40 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
14d50 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14d60 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
14d70 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
14d80 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
14d90 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
14da0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14db0 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
14dc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
14dd0 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
14de0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
14df0 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
14e00 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
14e10 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
14e20 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
14e30 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
14e40 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
14e50 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
14e60 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
14e70 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
14e80 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
14e90 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
14ea0 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
14eb0 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
14ec0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
14ed0 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
14ee0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14ef0 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
14f00 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14f10 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
14f20 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
14f30 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
14f40 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
14f50 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
14f60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
14f70 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
14f80 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
14f90 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14fa0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
14fb0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
14fc0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
14fd0 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
14fe0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
14ff0 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
15000 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
15010 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
15020 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
15030 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
15040 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
15050 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
15060 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
15070 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
15080 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
15090 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
150a0 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
150b0 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
150c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
150d0 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
150e0 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
150f0 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
15100 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
15110 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
15120 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
15130 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
15140 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
15150 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15160 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
15170 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
15180 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
15190 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
151a0 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
151b0 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
151c0 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
151d0 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
151e0 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
151f0 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
15200 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
15210 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
15220 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
15230 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
15240 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
15250 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
15260 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
15270 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15280 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
15290 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
152a0 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
152b0 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
152c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
152d0 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
152e0 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
152f0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15300 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77  d mmap size.** w
15310 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20  ill be silently 
15320 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63  truncated if nec
15330 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69  essary so that i
15340 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65  t does not excee
15350 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d the.** compile
15360 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
15370 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
15380 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
15390 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
153a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
153b0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
153c0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
153d0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
153e0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
153f0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
15400 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
15410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
15420 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
15430 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15440 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
15450 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15460 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
15470 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15480 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15490 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20  HEAPSIZE option 
154a0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
154b0 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a  e if SQLite is.*
154c0 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  * compiled for W
154d0 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20  indows with the 
154e0 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  [SQLITE_WIN32_MA
154f0 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOC] pre-proces
15500 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66  sor macro.** def
15510 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f  ined. ^SQLITE_CO
15520 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15530 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
15540 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
15550 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
15560 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
15570 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
15580 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
15590 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ..** </dl>.**.**
155a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
155b0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
155c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
155d0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
155e0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
155f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15600 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
15610 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
15620 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
15630 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
15640 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
15650 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
15660 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
15670 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
15680 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
15690 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
156a0 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
156b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
156c0 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
156d0 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
156e0 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
156f0 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
15700 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
15710 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
15720 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
15730 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  version..**.** [
15740 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15750 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  MASZ]].** <dt>SQ
15760 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
15770 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
15780 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
15790 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
157a0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
157b0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e  r which.** is an
157c0 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
157d0 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22  r and sets the "
157e0 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  Minimum PMA Size
157f0 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74  " for the multit
15800 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65  hreaded.** sorte
15810 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  r to that intege
15820 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
15830 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  minimum PMA Size
15840 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a   is set by the.*
15850 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52  * [SQLITE_SORTER
15860 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d  _PMASZ] compile-
15870 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65  time option.  Ne
15880 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61  w threads are la
15890 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c  unched.** to hel
158a0 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72  p with sort oper
158b0 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74  ations when mult
158c0 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e  ithreaded sortin
158d0 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20  g.** is enabled 
158e0 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47  (using the [PRAG
158f0 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d  MA threads] comm
15900 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f  and) and the amo
15910 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a  unt of content.*
15920 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65  * to be sorted e
15930 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20  xceeds the page 
15940 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d  size times the m
15950 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a  inimum of the.**
15960 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73   [PRAGMA cache_s
15970 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64  ize] setting and
15980 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20   this value..** 
15990 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
159a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
159b0 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
159c0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
159d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
159e0 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
159f0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15a00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15a10 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
15a20 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15a30 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15a40 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
15a50 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
15a60 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
15a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15a80 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
15a90 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
15aa0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
15ab0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15ac0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
15ad0 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
15ae0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
15af0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15b00 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
15b10 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
15b20 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
15b30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15b40 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
15b50 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
15b60 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
15b70 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
15b80 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15b90 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
15ba0 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
15bb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15bc0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
15bd0 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
15be0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
15bf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15c00 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15c10 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
15c20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
15c30 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
15c40 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
15c50 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
15c60 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
15c70 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
15c80 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15c90 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
15ca0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
15cb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15cc0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
15cd0 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
15ce0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15cf0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15d00 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
15d10 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
15d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15d30 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
15d40 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
15d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15d60 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
15d70 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
15d80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15d90 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
15da0 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
15db0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
15dc0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
15dd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15de0 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
15df0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
15e00 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
15e10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15e20 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
15e30 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
15e40 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
15e50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
15e60 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
15e70 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
15e80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15e90 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
15ea0 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
15eb0 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
15ec0 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
15ed0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15ee0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
15ef0 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
15f00 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
15f10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15f20 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
15f30 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
15f40 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
15f50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
15f60 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
15f70 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
15f80 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a  int szPma */../*
15f90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
15fa0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
15fb0 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
15fc0 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
15fd0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
15fe0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
15ff0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
16000 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
16010 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
16020 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
16030 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
16040 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
16050 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
16060 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
16070 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16080 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
16090 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
160a0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
160b0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
160c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
160d0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
160e0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
160f0 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
16100 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
16110 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
16120 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16130 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
16140 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
16150 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
16160 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
16170 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
16180 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
16190 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
161a0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
161b0 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
161c0 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
161d0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
161e0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
161f0 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
16200 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16210 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
16220 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
16230 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
16240 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
16250 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
16260 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
16270 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
16280 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
16290 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
162a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
162b0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
162c0 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
162d0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
162e0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
162f0 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
16300 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
16310 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
16320 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
16330 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
16340 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
16350 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
16360 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
16370 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
16380 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
16390 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
163a0 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
163b0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
163c0 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
163d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
163e0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
163f0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
16400 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
16410 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
16420 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
16430 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
16440 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
16450 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
16460 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
16470 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16480 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
16490 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
164a0 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
164b0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
164c0 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
164d0 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
164e0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
164f0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
16500 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
16510 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16520 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
16530 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
16540 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
16550 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
16560 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
16570 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
16580 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
16590 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
165a0 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
165b0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
165c0 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
165d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
165e0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
165f0 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
16600 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
16610 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
16620 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
16630 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
16640 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
16650 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
16660 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
16670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
16680 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
16690 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
166a0 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
166b0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
166c0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
166d0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
166e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
166f0 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
16700 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
16710 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
16720 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
16730 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
16740 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
16750 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
16760 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
16770 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
16780 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
16790 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
167a0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
167b0 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
167c0 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
167d0 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
167e0 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
167f0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
16800 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
16810 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
16820 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
16830 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
16840 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
16850 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
16860 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
16870 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
16880 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
16890 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
168a0 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
168b0 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
168c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
168d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
168e0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
168f0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
16900 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
16910 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
16920 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
16930 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
16940 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
16950 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16960 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
16970 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
16980 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
16990 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
169a0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
169b0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
169c0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
169d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
169e0 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
169f0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
16a00 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
16a10 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
16a20 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
16a30 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
16a40 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
16a50 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
16a60 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
16a70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16a80 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
16a90 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
16aa0 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
16ab0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
16ac0 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
16ad0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
16ae0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
16af0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
16b00 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16b10 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
16b20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
16b30 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
16b40 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
16b50 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
16b60 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
16b70 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
16b80 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
16b90 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
16ba0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16bb0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
16bc0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
16bd0 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
16be0 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
16bf0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
16c00 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
16c10 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
16c20 49 47 5f 57 52 49 54 41 42 4c 45 5f 42 54 52 45  IG_WRITABLE_BTRE
16c30 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
16c40 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
16c50 73 65 64 20 74 6f 20 64 69 73 61 62 6c 65 20 49  sed to disable I
16c60 4e 53 45 52 54 20 61 6e 64 20 44 45 4c 45 54 45  NSERT and DELETE
16c70 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
16c80 67 61 69 6e 73 74 20 61 6c 6c 20 61 74 74 61 63  gainst all attac
16c90 68 65 64 20 62 2d 74 72 65 65 73 2c 20 65 78 63  hed b-trees, exc
16ca0 65 70 74 20 66 6f 72 20 62 2d 74 72 65 65 73 20  ept for b-trees 
16cb0 74 68 61 74 20 68 61 76 65 20 61 20 0a 2a 2a 20  that have a .** 
16cc0 70 61 72 74 69 63 75 6c 61 72 20 72 6f 6f 74 20  particular root 
16cd0 70 61 67 65 2e 20 0a 2a 2a 20 54 68 65 72 65 20  page. .** There 
16ce0 6d 75 73 74 20 62 65 20 6f 6e 65 20 61 64 64 69  must be one addi
16cf0 74 69 6f 6e 61 6c 20 69 6e 74 65 67 65 72 20 61  tional integer a
16d00 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
16d10 20 74 68 65 20 72 6f 6f 74 20 70 61 67 65 0a 2a   the root page.*
16d20 2a 20 74 68 61 74 20 69 73 20 61 6c 6c 6f 77 65  * that is allowe
16d30 64 20 74 6f 20 62 65 20 77 72 69 74 74 65 6e 2e  d to be written.
16d40 20 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e    If the argumen
16d50 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 0a  t is zero, then.
16d60 2a 2a 20 77 72 69 74 69 6e 67 20 69 73 20 61 6c  ** writing is al
16d70 6c 6f 77 65 64 20 74 6f 20 61 6c 6c 20 62 2d 74  lowed to all b-t
16d80 72 65 65 73 2c 20 61 73 20 69 73 20 6e 6f 72 6d  rees, as is norm
16d90 61 6c 6c 79 20 74 68 65 20 63 61 73 65 2e 0a 2a  ally the case..*
16da0 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
16db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
16dc0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
16dd0 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
16de0 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
16df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16e00 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
16e10 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
16e20 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
16e30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
16e40 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
16e50 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
16e60 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
16e70 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
16e80 47 5f 57 52 49 54 41 42 4c 45 5f 42 54 52 45 45  G_WRITABLE_BTREE
16e90 20 20 31 30 30 34 20 20 2f 2a 20 69 6e 74 20 2a    1004  /* int *
16ea0 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
16eb0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
16ec0 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
16ed0 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
16ee0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
16ef0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
16f00 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
16f10 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
16f20 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
16f30 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
16f40 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
16f50 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
16f60 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
16f70 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
16f80 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
16f90 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
16fa0 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
16fb0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
16fc0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
16fd0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
16fe0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
16ff0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
17000 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
17010 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
17020 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
17030 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
17040 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
17050 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
17060 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
17070 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
17080 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
17090 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
170a0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
170b0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
170c0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
170d0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
170e0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
170f0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
17100 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
17110 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
17120 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
17130 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
17140 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
17150 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
17160 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
17170 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
17180 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
17190 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
171a0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
171b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
171c0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
171d0 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
171e0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
171f0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
17200 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
17210 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17220 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
17230 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
17240 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
17250 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17260 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
17270 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
17280 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
17290 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
172a0 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
172b0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
172c0 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
172d0 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
172e0 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
172f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17300 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
17310 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17320 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
17330 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
17340 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
17350 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
17360 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
17370 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
17380 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
17390 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
173a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
173b0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
173c0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
173d0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
173e0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
173f0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
17400 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
17410 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
17420 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
17430 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
17440 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17450 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
17460 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
17470 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
17480 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
17490 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
174a0 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
174b0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
174c0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
174d0 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
174e0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
174f0 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
17500 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
17510 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
17520 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
17530 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
17540 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
17550 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
17560 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
17570 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
17580 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
17590 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
175a0 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
175b0 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
175c0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
175d0 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
175e0 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
175f0 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
17600 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
17610 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
17620 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
17630 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
17640 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
17650 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
17660 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
17670 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
17680 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
17690 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
176a0 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
176b0 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
176c0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
176d0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
176e0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
176f0 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
17700 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
17710 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
17720 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
17730 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
17740 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
17750 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
17760 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
17770 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
17780 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
17790 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
177a0 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
177b0 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
177c0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
177d0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
177e0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
177f0 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
17800 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
17810 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
17820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
17830 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
17840 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17850 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
17860 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
17870 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
17880 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
17890 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
178a0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
178b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
178c0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
178d0 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
178e0 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
178f0 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
17900 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
17910 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
17920 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
17930 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
17940 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17950 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
17960 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17970 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
17980 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
17990 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
179a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
179b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
179c0 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c  f rows modified,
179d0 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20   inserted or.** 
179e0 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
179f0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
17a00 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
17a10 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a  PDATE or DELETE.
17a20 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20  ** statement on 
17a30 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17a40 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  nection specifie
17a50 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61  d by the only pa
17a60 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65  rameter..** ^Exe
17a70 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
17a80 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
17a90 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
17aa0 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65  modify the value
17ab0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
17ac0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
17ad0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67  *.** ^Only chang
17ae0 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79  es made directly
17af0 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20   by the INSERT, 
17b00 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
17b10 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a   statement are.*
17b20 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61  * considered - a
17b30 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
17b40 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41   caused by [CREA
17b50 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
17b60 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72  ggers], .** [for
17b70 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
17b80 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63  ] or [REPLACE] c
17b90 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
17ba0 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75  tion are not cou
17bb0 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61  nted..** .** Cha
17bc0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
17bd0 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
17be0 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54  ted by .** [INST
17bf0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c  EAD OF trigger |
17c00 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
17c10 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  gers] are not co
17c20 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75  unted. ^The valu
17c30 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  e .** returned b
17c40 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
17c50 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  s() immediately 
17c60 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c  after an INSERT,
17c70 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44   UPDATE or .** D
17c80 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
17c90 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73  run on a view is
17ca0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e   always zero. On
17cb0 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
17cc0 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c  to real .** tabl
17cd0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17ce0 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65  **.** Things are
17cf0 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65   more complicate
17d00 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33  d if the sqlite3
17d10 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
17d20 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74  ion is.** execut
17d30 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67  ed while a trigg
17d40 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75  er program is ru
17d50 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20  nning. This may 
17d60 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a  happen if the.**
17d70 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68   program uses th
17d80 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
17d90 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69   function], or i
17da0 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c  f some other cal
17db0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
17dc0 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65  n invokes sqlite
17dd0 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65  3_changes() dire
17de0 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c  ctly. Essentiall
17df0 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y:.** .** <ul>.*
17e00 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72  *   <li> ^(Befor
17e10 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69  e entering a tri
17e20 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65  gger program the
17e30 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
17e40 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c  by.**        sql
17e50 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
17e60 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64  unction is saved
17e70 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67  . After the trig
17e80 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20  ger program .** 
17e90 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73         has finis
17ea0 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61  hed, the origina
17eb0 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f  l value is resto
17ec0 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20  red.)^.** .**   
17ed0 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20  <li> ^(Within a 
17ee0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
17ef0 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44  each INSERT, UPD
17f00 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a  ATE and DELETE .
17f10 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d  **        statem
17f20 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c  ent sets the val
17f30 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
17f40 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17f50 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e   .**        upon
17f60 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e   completion as n
17f70 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65  ormal. Of course
17f80 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c  , this value wil
17f90 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a  l not include .*
17fa0 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61  *        any cha
17fb0 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62  nges performed b
17fc0 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20  y sub-triggers, 
17fd0 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  as the sqlite3_c
17fe0 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
17ff0 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62      value will b
18000 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74  e saved and rest
18010 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20  ored after each 
18020 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20  sub-trigger has 
18030 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  run.)^.** </ul>.
18040 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61  ** .** ^This mea
18050 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63  ns that if the c
18060 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
18070 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61  ction (or simila
18080 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79  r) is used.** by
18090 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52   the first INSER
180a0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
180b0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
180c0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
180d0 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  it .** returns t
180e0 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20  he value as set 
180f0 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67  when the calling
18100 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e   statement began
18110 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
18120 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79  If it is used by
18130 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73   the second or s
18140 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73  ubsequent such s
18150 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
18160 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72  a trigger .** pr
18170 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65  ogram, the value
18180 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63   returned reflec
18190 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ts the number of
181a0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62   rows modified b
181b0 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f  y the .** previo
181c0 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  us INSERT, UPDAT
181d0 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
181e0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
181f0 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
18200 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
18210 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
18220 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
18230 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
18240 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
18250 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
18260 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
18270 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
18280 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
18290 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
182a0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
182b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
182c0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
182d0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
182e0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
182f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18300 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
18310 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
18320 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
18330 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18340 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
18350 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
18360 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
18370 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
18380 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
18390 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
183a0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
183b0 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
183c0 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
183d0 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
183e0 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
183f0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
18400 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
18410 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
18420 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
18430 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
18440 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
18450 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
18460 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
18470 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
18480 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
18490 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
184a0 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
184b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
184c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
184d0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
184e0 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
184f0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
18500 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
18510 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
18520 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
18530 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
18540 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
18550 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
18560 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
18570 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
18580 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
18590 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
185a0 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
185b0 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
185c0 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
185d0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
185e0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
185f0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
18600 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
18610 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
18620 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
18630 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
18640 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
18650 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
18660 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
18670 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
18680 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
18690 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
186a0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
186b0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
186c0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
186d0 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
186e0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
186f0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
18700 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
18710 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
18720 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
18730 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
18740 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
18750 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
18760 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
18770 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
18780 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
18790 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
187a0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
187b0 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
187c0 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
187d0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
187e0 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
187f0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
18800 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
18810 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
18820 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
18830 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
18840 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
18850 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
18860 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
18870 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
18880 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
18890 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
188a0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
188b0 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
188c0 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
188d0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
188e0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
188f0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
18900 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
18910 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
18920 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
18930 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
18940 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
18950 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
18960 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
18970 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
18980 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
18990 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
189a0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
189b0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
189c0 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
189d0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
189e0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
189f0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
18a00 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
18a10 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
18a20 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
18a30 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
18a40 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
18a50 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
18a60 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
18a70 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
18a80 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
18a90 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
18aa0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
18ab0 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
18ac0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
18ad0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
18ae0 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
18af0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
18b00 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
18b10 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
18b20 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
18b30 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
18b40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
18b50 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
18b60 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
18b70 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
18b80 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
18b90 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
18ba0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
18bb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
18bc0 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
18bd0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
18be0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
18bf0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
18c00 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18c10 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
18c20 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
18c30 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
18c40 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
18c50 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
18c60 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
18c70 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
18c80 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
18c90 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
18ca0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
18cb0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
18cc0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
18cd0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
18ce0 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
18cf0 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
18d00 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
18d10 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18d20 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
18d30 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
18d40 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
18d50 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
18d60 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
18d70 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
18d80 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
18d90 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
18da0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
18db0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
18dc0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
18dd0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18de0 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
18df0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
18e00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18e10 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
18e20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
18e30 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
18e40 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
18e50 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
18e60 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
18e70 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18e80 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
18e90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
18ea0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
18eb0 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
18ec0 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
18ed0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
18ee0 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
18ef0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
18f00 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
18f10 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
18f20 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
18f30 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
18f40 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
18f50 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
18f60 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
18f70 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
18f80 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
18f90 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
18fa0 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
18fb0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
18fc0 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
18fd0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
18fe0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
18ff0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
19000 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
19010 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
19020 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
19030 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
19040 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
19050 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
19060 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
19070 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
19080 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
19090 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
190a0 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
190b0 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
190c0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
190d0 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
190e0 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
190f0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
19100 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
19110 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
19120 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
19130 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
19140 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
19150 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
19160 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
19170 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
19180 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
19190 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
191a0 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
191b0 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
191c0 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
191d0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
191e0 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
191f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
19200 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
19210 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
19220 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
19230 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
19240 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
19250 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
19260 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
19270 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
19280 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
19290 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
192a0 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
192b0 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
192c0 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
192d0 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
192e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
192f0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
19300 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
19310 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
19320 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
19330 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
19340 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
19350 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
19360 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
19370 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
19380 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
19390 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
193a0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
193b0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
193c0 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
193d0 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
193e0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
193f0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
19400 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
19410 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
19420 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
19430 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
19440 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
19450 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
19460 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
19470 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
19480 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19490 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
194a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
194b0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
194c0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
194d0 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
194e0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
194f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
19500 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
19510 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
19520 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
19530 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
19540 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
19550 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
19560 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45  USY Errors.** KE
19570 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61  YWORDS: {busy-ha
19580 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20  ndler callback} 
19590 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a  {busy handler}.*
195a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
195b0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
195c0 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
195d0 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
195e0 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
195f0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
19600 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
19610 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
19620 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
19630 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
19640 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
19650 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
19660 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19670 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
19680 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
19690 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
196a0 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
196b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
196c0 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
196d0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
196e0 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
196f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
19700 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
19710 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
19720 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
19730 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
19740 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
19750 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
19760 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
19770 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
19780 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
19790 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
197a0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
197b0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
197c0 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
197d0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
197e0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
197f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
19800 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
19810 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
19820 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
19830 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
19840 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
19850 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
19860 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19870 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
19880 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
19890 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
198a0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
198b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
198c0 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
198d0 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
198e0 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72   been invoked pr
198f0 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65  eviously for the
19900 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
19910 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
19920 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
19930 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
19940 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
19950 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
19960 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
19970 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
19980 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65  LITE_BUSY] is re
19990 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65  turned.** to the
199a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
199b0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
199c0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
199d0 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
199e0 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
199f0 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68  ade to access th
19a00 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
19a10 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
19a20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
19a30 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
19a40 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
19a50 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
19a60 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
19a70 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
19a80 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
19a90 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
19aa0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
19ab0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
19ac0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
19ad0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
19ae0 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
19af0 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
19b00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
19b10 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  ].** to the appl
19b20 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20  ication instead 
19b30 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
19b40 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
19b50 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
19b60 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
19b70 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
19b80 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
19b90 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
19ba0 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
19bb0 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
19bc0 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
19bd0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
19be0 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
19bf0 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
19c00 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
19c10 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
19c20 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
19c30 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
19c40 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
19c50 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
19c60 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
19c70 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
19c80 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
19c90 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
19ca0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
19cb0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
19cc0 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
19cd0 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
19ce0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19cf0 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
19d00 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
19d10 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
19d20 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
19d30 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
19d40 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
19d50 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
19d60 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
19d70 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
19d80 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
19d90 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
19da0 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
19db0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
19dc0 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
19dd0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
19de0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
19df0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s NULL..**.** ^(
19e00 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
19e10 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
19e20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
19e30 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
19e40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19e50 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
19e60 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
19e70 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
19e80 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
19e90 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
19ea0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
19eb0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
19ec0 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61  ()].** or evalua
19ed0 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73  ting [PRAGMA bus
19ee0 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c  y_timeout=N] wil
19ef0 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  l change the.** 
19f00 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64  busy handler and
19f10 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20   thus clear any 
19f20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62  previously set b
19f30 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
19f40 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
19f50 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
19f60 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
19f70 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
19f80 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
19f90 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
19fa0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
19fb0 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65  andler.  In othe
19fc0 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20  r words,.** the 
19fd0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
19fe0 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20  not reentrant.  
19ff0 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
1a000 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
1a010 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1a020 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
1a030 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1a040 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
1a050 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1a060 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1a070 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1a080 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1a090 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20  handler..*/.int 
1a0a0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1a0b0 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1a0c0 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
1a0d0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1a0e0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1a0f0 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1a100 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1a110 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1a120 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1a130 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1a140 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1a150 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1a160 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1a170 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1a180 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1a190 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1a1a0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1a1b0 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1a1c0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1a1d0 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1a1e0 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1a1f0 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1a200 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1a210 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1a220 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1a230 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1a240 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1a250 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1a260 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1a270 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1a280 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1a290 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1a2a0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1a2b0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1a2c0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1a2d0 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1a2e0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1a2f0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1a300 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1a310 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1a320 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a330 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1a340 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1a350 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1a360 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1a370 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1a380 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a390 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1a3a0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1a3b0 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1a3c0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1a3d0 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1a3e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1a3f0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1a400 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  out].*/.int sqli
1a410 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1a420 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
1a430 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
1a440 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
1a450 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
1a460 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
1a470 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1a480 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1a490 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1a4a0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1a4b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1a4c0 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1a4d0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1a4e0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1a4f0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1a500 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1a510 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1a520 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1a530 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1a540 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a550 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1a560 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1a570 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1a580 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1a590 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1a5a0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1a5b0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1a5c0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1a5d0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1a5e0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1a5f0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1a600 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1a610 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1a620 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1a630 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1a640 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1a650 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1a660 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1a670 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1a680 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1a690 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1a6a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1a6b0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1a6c0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1a6d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1a6e0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1a6f0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1a700 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1a710 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1a720 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1a730 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1a740 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1a750 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1a760 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1a770 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1a780 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1a790 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1a7a0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1a7b0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1a7c0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1a7d0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1a7e0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1a7f0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1a800 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1a810 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1a820 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1a830 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1a840 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1a850 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1a860 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1a870 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1a880 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1a890 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1a8a0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1a8b0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1a8c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1a8d0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1a8e0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1a8f0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1a900 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1a910 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1a920 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1a930 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1a940 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1a950 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1a960 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1a970 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1a980 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a990 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1a9a0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1a9b0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1a9c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1a9d0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1a9e0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1a9f0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1aa00 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1aa10 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1aa20 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1aa30 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1aa40 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1aa50 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1aa60 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1aa70 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1aa80 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1aa90 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1aaa0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1aab0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1aac0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1aad0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1aae0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1aaf0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1ab00 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1ab10 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1ab20 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1ab30 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1ab40 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ab50 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1ab60 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1ab70 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1ab80 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1ab90 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1aba0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1abb0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1abc0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1abd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1abe0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1abf0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1ac00 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1ac10 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ac20 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1ac30 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ac40 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1ac50 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1ac60 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1ac70 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1ac80 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1ac90 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1aca0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1acb0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1acc0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1acd0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1ace0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1acf0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1ad00 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1ad10 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1ad20 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1ad30 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1ad40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1ad50 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1ad60 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1ad70 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ad80 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1ad90 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1ada0 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1adb0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1adc0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1add0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1ade0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1adf0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1ae00 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1ae10 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1ae20 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1ae30 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1ae40 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1ae50 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1ae60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1ae70 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1ae80 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1ae90 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1aea0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1aeb0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1aec0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1aed0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1aee0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1aef0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1af00 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1af10 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1af20 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1af30 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1af40 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1af50 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1af60 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1af70 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1af80 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1af90 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1afa0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1afb0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1afc0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1afd0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1afe0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1aff0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1b000 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1b010 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1b020 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1b030 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1b040 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1b050 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1b060 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1b070 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1b080 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1b090 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1b0a0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1b0b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1b0c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1b0d0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1b0e0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1b0f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1b100 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1b110 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1b120 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1b130 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1b140 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1b150 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1b160 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1b170 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1b180 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1b190 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1b1a0 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1b1b0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1b1c0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1b1d0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1b1e0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1b1f0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1b200 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1b210 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1b220 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1b230 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1b240 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1b250 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1b260 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1b270 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b280 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1b290 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1b2a0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1b2b0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1b2c0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1b2d0 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
1b2e0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1b2f0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1b300 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1b310 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1b320 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1b330 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1b340 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1b350 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1b360 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1b370 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1b380 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1b390 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1b3a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1b3b0 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1b3c0 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1b3d0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1b3e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1b3f0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1b400 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1b410 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1b420 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1b430 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1b440 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1b450 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1b460 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1b470 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1b480 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1b490 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1b4a0 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1b4b0 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1b4c0 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1b4d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1b4e0 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1b4f0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1b500 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1b510 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1b520 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1b530 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1b540 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1b550 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1b560 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1b570 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1b580 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1b590 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1b5a0 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1b5b0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1b5c0 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1b5d0 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1b5e0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1b5f0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1b600 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1b610 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1b620 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1b630 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1b640 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1b650 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1b660 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1b670 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1b680 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1b690 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1b6a0 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1b6b0 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1b6c0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1b6d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1b6e0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b6f0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1b700 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1b710 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1b720 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1b730 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1b740 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1b750 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1b760 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1b770 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1b780 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1b790 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1b7a0 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1b7b0 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1b7c0 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1b7d0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1b7e0 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1b7f0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1b800 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1b810 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1b820 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1b830 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1b840 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1b850 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1b860 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1b870 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1b880 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1b890 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1b8a0 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1b8b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b8c0 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1b8d0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1b8e0 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1b8f0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1b900 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1b910 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1b920 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1b930 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1b940 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1b950 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1b960 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1b970 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1b980 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
1b990 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
1b9a0 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
1b9b0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
1b9c0 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
1b9d0 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
1b9e0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
1b9f0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
1ba00 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
1ba10 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
1ba20 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
1ba30 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
1ba40 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
1ba50 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
1ba60 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
1ba70 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
1ba80 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
1ba90 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
1baa0 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
1bab0 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
1bac0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
1bad0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
1bae0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
1baf0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1bb00 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1bb10 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1bb20 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1bb30 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1bb40 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1bb50 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1bb60 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1bb70 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1bb80 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1bb90 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1bba0 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1bbb0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1bbc0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1bbd0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1bbe0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1bbf0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1bc00 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1bc10 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1bc20 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1bc30 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1bc40 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1bc50 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1bc60 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1bc70 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1bc80 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1bc90 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1bca0 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1bcb0 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1bcc0 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1bcd0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1bce0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1bcf0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1bd00 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1bd10 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1bd20 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1bd30 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1bd40 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1bd50 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1bd60 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1bd70 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1bd80 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1bd90 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1bda0 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1bdb0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1bdc0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1bdd0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1bde0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1bdf0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1be00 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1be10 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1be20 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1be30 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1be40 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1be50 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1be60 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1be70 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1be80 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1be90 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1bea0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1beb0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1bec0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1bed0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1bee0 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1bef0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1bf00 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1bf10 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1bf20 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1bf30 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1bf40 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1bf50 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1bf60 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1bf70 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1bf80 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1bf90 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1bfa0 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1bfb0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1bfc0 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1bfd0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1bfe0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1bff0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1c000 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1c010 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1c020 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1c030 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1c040 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1c050 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1c060 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1c070 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1c080 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1c090 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1c0a0 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1c0b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1c0c0 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1c0d0 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1c0e0 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1c0f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1c100 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1c110 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1c120 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1c130 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1c140 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1c150 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1c160 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1c170 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1c180 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1c190 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1c1a0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1c1b0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1c1c0 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
1c1d0 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
1c1e0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
1c1f0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
1c200 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
1c210 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
1c220 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1c230 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1c240 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
1c250 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1c260 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1c270 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1c280 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1c290 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1c2a0 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1c2b0 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1c2c0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1c2d0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1c2e0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1c2f0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1c300 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1c310 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1c320 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1c330 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1c340 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1c350 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1c360 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1c370 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1c380 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1c390 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1c3a0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1c3b0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1c3c0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1c3d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c3e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1c3f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1c400 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1c410 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1c420 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1c430 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1c440 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1c450 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c460 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1c470 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1c480 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1c490 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1c4a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1c4b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1c4c0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1c4d0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1c4e0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1c4f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1c500 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1c510 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1c520 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c530 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
1c540 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
1c550 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
1c560 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
1c570 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
1c580 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
1c590 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1c5a0 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
1c5b0 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
1c5c0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1c5d0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1c5e0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1c5f0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1c600 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1c610 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1c620 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1c630 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1c640 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1c650 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1c660 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1c670 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1c680 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1c690 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1c6a0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1c6b0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1c6c0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1c6d0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1c6e0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1c6f0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1c700 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1c710 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1c720 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1c730 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1c740 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1c750 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1c760 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1c770 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1c780 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1c790 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1c7a0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1c7b0 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1c7c0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1c7d0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1c7e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1c7f0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1c800 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1c810 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1c820 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1c830 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1c840 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1c850 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
1c860 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c870 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
1c880 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1c890 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1c8a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c8b0 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
1c8c0 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
1c8d0 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
1c8e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1c8f0 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
1c900 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1c910 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1c920 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1c930 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1c940 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
1c950 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
1c960 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1c970 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
1c980 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1c990 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1c9a0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1c9b0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1c9c0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1c9d0 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
1c9e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1c9f0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1ca00 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1ca10 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1ca20 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1ca30 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1ca40 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
1ca50 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
1ca60 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1ca70 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1ca80 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1ca90 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1caa0 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1cab0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1cac0 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1cad0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1cae0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1caf0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1cb00 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1cb10 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1cb20 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1cb30 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1cb40 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
1cb50 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
1cb60 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
1cb70 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
1cb80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
1cb90 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
1cba0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1cbb0 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
1cbc0 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
1cbd0 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
1cbe0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1cbf0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1cc00 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
1cc10 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
1cc20 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
1cc30 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
1cc40 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
1cc50 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
1cc60 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
1cc70 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1cc80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1cc90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1cca0 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
1ccb0 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
1ccc0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1ccd0 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
1cce0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1ccf0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
1cd00 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
1cd10 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
1cd20 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
1cd30 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1cd40 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
1cd50 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
1cd60 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
1cd70 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
1cd80 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
1cd90 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
1cda0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1cdb0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1cdc0 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1cdd0 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
1cde0 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
1cdf0 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
1ce00 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1ce10 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
1ce20 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
1ce30 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
1ce40 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
1ce50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
1ce60 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
1ce70 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
1ce80 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
1ce90 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1cea0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
1ceb0 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
1cec0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1ced0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1cee0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1cef0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1cf00 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1cf10 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
1cf20 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1cf30 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
1cf40 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1cf50 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1cf60 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1cf70 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1cf80 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1cf90 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1cfa0 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1cfb0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1cfc0 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1cfd0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1cfe0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1cff0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1d000 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1d010 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1d020 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1d030 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1d040 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1d050 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1d060 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1d070 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1d080 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1d090 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1d0a0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1d0b0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1d0c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1d0d0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1d0e0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1d0f0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1d100 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
1d110 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1d120 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
1d130 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1d140 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1d150 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1d160 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1d170 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1d180 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1d190 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1d1a0 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1d1b0 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1d1c0 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1d1d0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1d1e0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1d1f0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1d200 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
1d210 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
1d220 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
1d230 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1d240 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1d250 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1d260 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1d270 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1d280 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1d290 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1d2a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1d2b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1d2c0 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1d2d0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1d2e0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1d2f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1d300 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1d310 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1d320 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1d330 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1d340 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1d350 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1d360 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1d370 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1d380 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1d390 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1d3a0 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1d3b0 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1d3c0 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1d3d0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1d3e0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1d3f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1d400 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1d410 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
1d420 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1d430 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
1d440 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  64);.void *sqlit
1d450 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
1d460 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  , int);.void *sq
1d470 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1d480 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
1d490 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
1d4a0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1d4b0 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  ;.sqlite3_uint64
1d4c0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76   sqlite3_msize(v
1d4d0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1d4e0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1d4f0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1d500 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1d510 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1d520 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1d530 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1d540 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1d550 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1d560 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1d570 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1d580 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d590 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1d5a0 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1d5b0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1d5c0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1d5d0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1d5e0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1d5f0 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1d600 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1d610 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1d620 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1d630 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1d640 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1d650 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1d660 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d670 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1d680 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1d690 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1d6a0 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1d6b0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1d6c0 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1d6d0 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1d6e0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1d6f0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1d700 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1d710 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1d720 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1d730 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1d740 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1d750 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1d760 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1d770 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1d780 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1d790 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1d7a0 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1d7b0 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1d7c0 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1d7d0 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1d7e0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1d7f0 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1d800 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1d810 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1d820 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1d830 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1d840 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1d850 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1d860 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1d870 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1d880 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1d890 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1d8a0 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1d8b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1d8c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1d8d0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1d8e0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1d8f0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1d900 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1d910 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
1d920 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1d930 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
1d940 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1d950 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1d960 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
1d970 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d980 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
1d990 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
1d9a0 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
1d9b0 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
1d9c0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
1d9d0 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
1d9e0 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
1d9f0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
1da00 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
1da10 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
1da20 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
1da30 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
1da40 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
1da50 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
1da60 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
1da70 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
1da80 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
1da90 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
1daa0 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
1dab0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
1dac0 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
1dad0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
1dae0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
1daf0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
1db00 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
1db10 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
1db20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
1db30 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
1db40 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
1db50 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
1db60 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61   P..** ^The P pa
1db70 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61  rameter can be a
1db80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1db90 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
1dba0 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
1dbb0 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
1dbc0 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
1dbd0 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
1dbe0 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
1dbf0 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  one or a NULL po
1dc00 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65  inter for P, the
1dc10 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a  n the PRNG is.**
1dc20 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
1dc30 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
1dc40 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  d from the xRand
1dc50 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1dc60 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
1dc70 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1dc80 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ject..** ^If the
1dc90 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
1dca0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  o this routine h
1dcb0 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20  ad an N of 1 or 
1dcc0 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f  more and a.** no
1dcd0 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68  n-NULL P then th
1dce0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
1dcf0 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
1dd00 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
1dd10 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
1dd20 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
1dd30 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
1dd40 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
1dd50 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1dd60 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
1dd70 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
1dd80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1dd90 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
1dda0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
1ddb0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
1ddc0 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
1ddd0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
1dde0 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
1ddf0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1de00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1de10 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
1de20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1de30 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
1de40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1de50 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
1de60 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
1de70 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
1de80 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
1de90 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1dea0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
1deb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1dec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1ded0 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
1dee0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1def0 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
1df00 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
1df10 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
1df20 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
1df30 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
1df40 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
1df50 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
1df60 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
1df70 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1df80 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
1df90 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
1dfa0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
1dfb0 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
1dfc0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
1dfd0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
1dfe0 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
1dff0 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
1e000 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1e010 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
1e020 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
1e030 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
1e040 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1e050 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
1e060 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
1e070 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
1e080 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
1e090 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1e0a0 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
1e0b0 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
1e0c0 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
1e0d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1e0e0 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
1e0f0 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1e100 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
1e110 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
1e120 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
1e130 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
1e140 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1e150 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1e160 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1e170 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
1e180 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1e190 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1e1a0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
1e1b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1e1c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
1e1d0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
1e1e0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
1e1f0 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
1e200 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
1e210 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1e220 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
1e230 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e240 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1e250 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1e260 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
1e270 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1e280 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1e290 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
1e2a0 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
1e2b0 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
1e2c0 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
1e2d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1e2e0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e2f0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
1e300 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
1e310 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
1e320 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
1e330 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
1e340 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
1e350 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
1e360 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1e370 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
1e380 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
1e390 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
1e3a0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
1e3b0 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
1e3c0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1e3d0 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
1e3e0 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
1e3f0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
1e400 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
1e410 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1e420 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
1e430 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
1e440 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
1e450 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
1e460 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1e470 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1e480 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1e490 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
1e4a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1e4b0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
1e4c0 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
1e4d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e4e0 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
1e4f0 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
1e500 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
1e510 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
1e520 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
1e530 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
1e540 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
1e550 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
1e560 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
1e570 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
1e580 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
1e590 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
1e5a0 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
1e5b0 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
1e5c0 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
1e5d0 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
1e5e0 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
1e5f0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1e600 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
1e610 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
1e620 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
1e630 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1e640 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
1e650 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
1e660 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
1e670 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
1e680 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
1e690 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
1e6a0 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
1e6b0 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
1e6c0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
1e6d0 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
1e6e0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1e6f0 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
1e700 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
1e710 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
1e720 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
1e730 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
1e740 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
1e750 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
1e760 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
1e770 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
1e780 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
1e790 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
1e7a0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
1e7b0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
1e7c0 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
1e7d0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
1e7e0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
1e7f0 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
1e800 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
1e810 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
1e820 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
1e830 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
1e840 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
1e850 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1e860 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
1e870 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
1e880 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
1e890 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
1e8a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
1e8b0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
1e8c0 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
1e8d0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
1e8e0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
1e8f0 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
1e900 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e910 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
1e920 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
1e930 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
1e940 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1e950 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
1e960 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
1e970 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
1e980 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
1e990 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
1e9a0 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
1e9b0 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
1e9c0 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
1e9d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1e9e0 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
1e9f0 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
1ea00 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
1ea10 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1ea20 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
1ea30 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
1ea40 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
1ea50 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
1ea60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
1ea70 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
1ea80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ea90 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
1eaa0 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
1eab0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1eac0 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
1ead0 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
1eae0 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
1eaf0 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
1eb00 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
1eb10 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
1eb20 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1eb30 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
1eb40 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
1eb50 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1eb60 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1eb70 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1eb80 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1eb90 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1eba0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1ebb0 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
1ebc0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
1ebd0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1ebe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ebf0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1ec00 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1ec10 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1ec20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ec30 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1ec40 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1ec50 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1ec60 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
1ec70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ec80 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
1ec90 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1eca0 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
1ecb0 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
1ecc0 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
1ecd0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1ece0 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
1ecf0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
1ed00 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
1ed10 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
1ed20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1ed30 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
1ed40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
1ed50 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
1ed60 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
1ed70 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
1ed80 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
1ed90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1eda0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
1edb0 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
1edc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1edd0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1ede0 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
1edf0 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
1ee00 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
1ee10 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
1ee20 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
1ee30 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
1ee40 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
1ee50 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
1ee60 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
1ee70 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
1ee80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ee90 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
1eea0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
1eeb0 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
1eec0 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
1eed0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1eee0 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
1eef0 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
1ef00 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
1ef10 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1ef20 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1ef30 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
1ef40 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
1ef50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ef60 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
1ef70 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
1ef80 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1ef90 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1efa0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1efb0 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
1efc0 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
1efd0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1efe0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
1eff0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
1f000 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
1f010 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
1f020 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
1f030 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
1f040 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
1f050 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1f060 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1f070 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
1f080 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1f090 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1f0a0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
1f0b0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
1f0c0 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
1f0d0 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74  conflict resolut
1f0e0 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74  ion mode].** ret
1f0f0 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b  urned from the [
1f100 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
1f110 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
1f120 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
1f130 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
1f140 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
1f150 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
1f160 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
1f170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1f180 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
1f190 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
1f1a0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
1f1b0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
1f1c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f1d0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
1f1e0 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
1f1f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1f200 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
1f210 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
1f220 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1f230 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
1f240 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
1f250 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
1f260 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
1f270 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
1f280 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1f290 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1f2a0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
1f2b0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1f2c0 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
1f2d0 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
1f2e0 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
1f2f0 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
1f300 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
1f310 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1f320 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
1f330 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
1f340 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
1f350 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
1f360 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
1f370 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
1f380 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1f390 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
1f3a0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
1f3b0 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
1f3c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1f3d0 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
1f3e0 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
1f3f0 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
1f400 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
1f410 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
1f420 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1f430 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
1f440 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
1f450 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
1f460 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
1f470 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1f480 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
1f490 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
1f4a0 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
1f4b0 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
1f4c0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1f4d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
1f4e0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1f4f0 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
1f500 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
1f510 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
1f520 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
1f530 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
1f540 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
1f550 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
1f560 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
1f570 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
1f580 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
1f590 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f5a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f5b0 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
1f5c0 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
1f5d0 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
1f5e0 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
1f5f0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
1f600 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f610 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f620 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f630 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
1f640 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
1f650 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f660 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f670 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f680 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
1f690 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
1f6a0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1f6b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f6c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f6d0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
1f6e0 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
1f6f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1f700 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f710 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f720 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
1f730 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
1f740 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1f750 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f760 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f770 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
1f780 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
1f790 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1f7a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f7b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1f7c0 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
1f7d0 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
1f7e0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1f7f0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f800 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1f810 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
1f820 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
1f830 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1f840 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f850 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
1f860 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1f870 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
1f880 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f890 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f8a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f8b0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1f8c0 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
1f8d0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1f8e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1f8f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1f900 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
1f910 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
1f920 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f930 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f940 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1f950 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
1f960 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1f970 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1f980 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f990 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1f9a0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
1f9b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f9c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f9d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f9e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1f9f0 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
1fa00 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1fa10 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1fa20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fa30 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1fa40 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
1fa50 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1fa60 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1fa70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fa80 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
1fa90 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
1faa0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1fab0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1fac0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fad0 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
1fae0 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
1faf0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1fb00 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fb10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fb20 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
1fb30 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
1fb40 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fb50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fb60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fb70 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
1fb80 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
1fb90 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
1fba0 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
1fbb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fbc0 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
1fbd0 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
1fbe0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1fbf0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1fc00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fc10 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1fc20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
1fc30 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
1fc40 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fc50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
1fc60 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
1fc70 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
1fc80 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
1fc90 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1fca0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
1fcb0 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
1fcc0 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
1fcd0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1fce0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1fcf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
1fd00 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1fd10 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
1fd20 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
1fd30 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1fd40 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
1fd50 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1fd60 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
1fd70 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
1fd80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fd90 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
1fda0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1fdb0 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
1fdc0 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
1fdd0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1fde0 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
1fdf0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
1fe00 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
1fe10 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1fe20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1fe30 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
1fe40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
1fe50 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1fe60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1fe70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fe80 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1fe90 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
1fea0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1feb0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1fec0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fed0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
1fee0 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
1fef0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1ff00 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1ff10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ff20 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
1ff30 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
1ff40 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1ff50 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
1ff60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ff70 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
1ff80 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
1ff90 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1ffa0 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
1ffb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ffc0 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
1ffd0 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
1ffe0 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
1fff0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20000 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20  E_RECURSIVE     
20010 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e         33   /* N
20020 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
20030 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20040 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
20050 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
20060 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
20070 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
20080 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
20090 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
200a0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
200b0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
200c0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
200d0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
200e0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
200f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
20100 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
20110 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
20120 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
20130 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
20140 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
20150 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
20160 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
20170 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
20180 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
20190 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
201a0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
201b0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
201c0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
201d0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
201e0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
201f0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
20200 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
20210 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
20220 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
20230 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
20240 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
20250 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
20260 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
20270 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
20280 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
20290 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
202a0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
202b0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
202c0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
202d0 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
202e0 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
202f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
20300 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
20310 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
20320 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
20330 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
20340 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
20350 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
20360 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
20370 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20380 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
20390 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
203a0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
203b0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
203c0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
203d0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
203e0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
203f0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
20400 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
20410 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
20420 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
20430 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
20440 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
20450 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
20460 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
20470 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
20480 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
20490 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
204a0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
204b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
204c0 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
204d0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
204e0 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
204f0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
20500 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
20510 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
20520 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
20530 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
20540 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
20550 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
20560 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
20570 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
20580 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
20590 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
205a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
205b0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
205c0 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
205d0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
205e0 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
205f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
20600 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
20610 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
20620 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
20630 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
20640 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
20650 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
20660 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
20670 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
20680 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
20690 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
206a0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
206b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
206c0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
206d0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
206e0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
206f0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
20700 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
20710 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
20720 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
20730 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
20740 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
20750 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
20760 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
20770 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
20780 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
20790 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
207a0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
207b0 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
207c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
207d0 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
207e0 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
207f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
20800 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
20810 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
20820 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
20830 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
20840 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
20850 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
20860 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
20870 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
20880 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
20890 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
208a0 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
208b0 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
208c0 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
208d0 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
208e0 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
208f0 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
20900 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
20910 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
20920 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
20930 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
20940 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
20950 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
20960 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
20970 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
20980 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
20990 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
209a0 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
209b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
209c0 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
209d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
209e0 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
209f0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
20a00 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
20a10 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
20a20 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
20a30 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
20a40 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
20a50 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
20a60 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
20a70 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
20a80 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
20a90 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
20aa0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20ab0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
20ac0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
20ad0 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
20ae0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
20af0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
20b00 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
20b10 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
20b20 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
20b30 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
20b40 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20b50 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
20b60 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
20b70 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
20b80 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
20b90 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
20ba0 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
20bb0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
20bc0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
20bd0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20be0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
20bf0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
20c00 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
20c10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
20c20 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
20c30 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
20c40 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
20c50 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
20c60 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
20c70 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
20c80 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
20c90 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
20ca0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
20cb0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
20cc0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
20cd0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
20ce0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
20cf0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
20d00 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
20d10 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
20d20 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
20d30 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
20d40 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
20d50 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
20d60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
20d70 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
20d80 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
20d90 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
20da0 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
20db0 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
20dc0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
20dd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
20de0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
20df0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
20e00 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
20e10 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
20e20 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
20e30 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
20e40 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
20e50 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
20e60 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
20e70 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
20e80 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
20e90 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
20ea0 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
20eb0 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
20ec0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
20ed0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
20ee0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
20ef0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
20f00 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
20f10 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
20f20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
20f30 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
20f40 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
20f50 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
20f60 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
20f70 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
20f80 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
20f90 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
20fa0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
20fb0 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
20fc0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
20fd0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
20fe0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
20ff0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
21000 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
21010 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
21020 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
21030 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77  fault encoding w
21040 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72  ill be UTF-8 for
21050 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74   databases creat
21060 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69  ed using.** sqli
21070 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
21080 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
21090 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65    ^The default e
210a0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61  ncoding for data
210b0 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  bases.** created
210c0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f   using sqlite3_o
210d0 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20  pen16() will be 
210e0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
210f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
21100 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
21110 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
21120 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
21130 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
21140 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
21150 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
21160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
21170 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
21180 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
21190 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
211a0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
211b0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
211c0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
211d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
211e0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
211f0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
21200 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
21210 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
21220 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
21230 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
21240 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
21250 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
21260 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
21270 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
21280 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
21290 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
212a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
212b0 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
212c0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
212d0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
212e0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
212f0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
21300 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
21310 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
21320 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
21330 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
21340 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
21350 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
21360 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
21370 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
21380 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
21390 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
213a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
213b0 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
213c0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
213d0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
213e0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
213f0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
21400 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
21410 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
21420 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
21430 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
21440 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
21450 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
21460 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
21470 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
21480 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
21490 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
214a0 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
214b0 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
214c0 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
214d0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
214e0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
214f0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
21500 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
21510 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
21520 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
21530 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
21540 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
21550 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
21560 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
21570 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
21580 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
21590 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
215a0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
215b0 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
215c0 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
215d0 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
215e0 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
215f0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
21600 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
21610 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
21620 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
21630 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
21640 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
21650 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
21660 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
21670 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21680 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
21690 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
216a0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
216b0 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
216c0 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
216d0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
216e0 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
216f0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
21700 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
21710 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
21720 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
21730 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
21740 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
21750 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
21760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
21770 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
21780 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
21790 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
217a0 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
217b0 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
217c0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
217d0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
217e0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
217f0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
21800 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
21810 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
21820 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
21830 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
21840 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
21850 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
21860 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
21870 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
21880 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
21890 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
218a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
218b0 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
218c0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
218d0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
218e0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
218f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21900 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
21910 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
21920 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
21930 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
21940 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
21950 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
21960 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
21970 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
21980 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
21990 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
219a0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
219b0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
219c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
219d0 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
219e0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
219f0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
21a00 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
21a10 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
21a20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
21a30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
21a40 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
21a50 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
21a60 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
21a70 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
21a80 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
21a90 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
21aa0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
21ab0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21ac0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
21ad0 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
21ae0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
21af0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21b00 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
21b10 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
21b20 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
21b30 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
21b40 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
21b50 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
21b60 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
21b70 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
21b80 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
21b90 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
21ba0 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
21bb0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
21bc0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
21bd0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
21be0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
21bf0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
21c00 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
21c10 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
21c20 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
21c30 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
21c40 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
21c50 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
21c60 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
21c70 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
21c80 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
21c90 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
21ca0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
21cb0 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
21cc0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
21cd0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
21ce0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
21cf0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
21d00 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
21d10 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
21d20 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
21d30 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
21d40 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
21d50 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
21d60 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
21d70 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
21d80 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
21d90 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
21da0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
21db0 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
21dc0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
21dd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
21de0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
21df0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
21e00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
21e10 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
21e20 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
21e30 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
21e40 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
21e50 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
21e60 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
21e70 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
21e80 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
21e90 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
21ea0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
21eb0 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
21ec0 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
21ed0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
21ee0 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
21ef0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
21f00 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
21f10 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
21f20 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
21f30 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
21f40 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
21f50 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
21f60 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
21f70 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
21f80 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
21f90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
21fa0 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
21fb0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
21fc0 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
21fd0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
21fe0 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
21ff0 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
22000 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
22010 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
22020 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
22030 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
22040 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
22050 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
22060 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
22070 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
22080 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
22090 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
220a0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
220b0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
220c0 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
220d0 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
220e0 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
220f0 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
22100 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
22110 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
22120 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
22130 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
22140 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
22150 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
22160 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
22170 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
22180 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
22190 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
221a0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
221b0 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
221c0 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
221d0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
221e0 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
221f0 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
22200 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
22210 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
22220 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
22230 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
22240 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
22250 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
22260 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
22270 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
22280 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
22290 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
222a0 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
222b0 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
222c0 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
222d0 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
222e0 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
222f0 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
22300 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
22310 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
22320 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
22330 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
22340 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
22350 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
22360 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e  th. .** ^(On win
22370 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
22380 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
22390 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
223a0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
223b0 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
223c0 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20   "C:").)^.**.** 
223d0 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
223e0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
223f0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
22400 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
22410 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
22420 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
22430 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
22440 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
22450 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
22460 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
22470 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
22480 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69  .** SQLite and i
22490 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53  ts built-in [VFS
224a0 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68  es] interpret th
224b0 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71  e.** following q
224c0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
224d0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
224e0 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
224f0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
22500 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
22510 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
22520 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
22530 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
22540 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
22550 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
22560 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
22570 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
22580 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
22590 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
225a0 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
225b0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
225c0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
225d0 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
225e0 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
225f0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
22600 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
22610 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
22620 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
22630 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22640 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
22650 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
22660 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
22670 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
22680 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
22690 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
226a0 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
226b0 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
226c0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
226d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
226e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
226f0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
22700 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
22710 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
22720 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
22730 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
22740 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
22750 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
22760 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
22770 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
22780 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
22790 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
227a0 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
227b0 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
227c0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
227d0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
227e0 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
227f0 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
22800 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
22810 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
22820 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
22830 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
22840 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
22850 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
22860 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
22870 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
22880 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
22890 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
228a0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
228b0 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
228c0 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
228d0 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
228e0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
228f0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
22900 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
22910 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
22920 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
22930 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
22940 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
22950 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
22960 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
22970 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
22980 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
22990 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
229a0 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
229b0 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
229c0 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
229d0 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
229e0 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
229f0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
22a00 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
22a10 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
22a20 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
22a30 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
22a40 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
22a50 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
22a60 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
22a70 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
22a80 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
22a90 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
22aa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
22ab0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
22ac0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
22ad0 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
22ae0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
22af0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
22b00 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
22b10 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
22b20 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
22b30 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
22b40 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
22b50 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
22b60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
22b70 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
22b80 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
22b90 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
22ba0 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
22bb0 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
22bc0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
22bd0 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
22be0 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
22bf0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
22c00 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
22c10 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
22c20 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
22c30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
22c40 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
22c50 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
22c60 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
22c70 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
22c80 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
22c90 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
22ca0 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
22cb0 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
22cc0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
22cd0 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
22ce0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
22cf0 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
22d00 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f  .**  <li> <b>pso
22d10 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77  w</b>: ^The psow
22d20 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63   parameter indic
22d30 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ates whether or 
22d40 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  not the.**     [
22d50 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
22d60 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
22d70 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
22d80 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
22d90 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
22da0 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
22db0 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
22dc0 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  des..**.**  <li>
22dd0 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20   <b>nolock</b>: 
22de0 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61  ^The nolock para
22df0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
22e00 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  an query paramet
22e10 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
22e20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20  if set disables 
22e30 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20  file locking in 
22e40 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
22e50 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a   modes.  This.**
22e60 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66       is useful f
22e70 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64  or accessing a d
22e80 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c  atabase on a fil
22e90 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65  esystem that doe
22ea0 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70  s not.**     sup
22eb0 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43  port locking.  C
22ec0 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73  aution:  Databas
22ed0 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67  e corruption mig
22ee0 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f  ht result if two
22ef0 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20  .**     or more 
22f00 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20  processes write 
22f10 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
22f20 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65  base and any one
22f30 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20   of those.**    
22f40 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20   processes uses 
22f50 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20  nolock=1..**.** 
22f60 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62   <li> <b>immutab
22f70 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d  le</b>: ^The imm
22f80 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72  utable parameter
22f90 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
22fa0 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
22fb0 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61  eter that indica
22fc0 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74  tes that the dat
22fd0 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74  abase file is st
22fe0 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72  ored on.**     r
22ff0 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20  ead-only media. 
23000 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65   ^When immutable
23010 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20   is set, SQLite 
23020 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
23030 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
23040 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
23050 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79  changed, even by
23060 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20   a process with 
23070 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72  higher.**     pr
23080 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20  ivilege, and so 
23090 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
230a0 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79  opened read-only
230b0 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67   and all locking
230c0 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e  .**     and chan
230d0 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ge detection is 
230e0 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69  disabled.  Cauti
230f0 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20  on: Setting the 
23100 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20  immutable.**    
23110 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64   property on a d
23120 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61  atabase file tha
23130 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63  t does in fact c
23140 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74  hange can result
23150 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72  .**     in incor
23160 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c  rect query resul
23170 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ts and/or [SQLIT
23180 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72  E_CORRUPT] error
23190 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c  s..**     See al
231a0 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  so: [SQLITE_IOCA
231b0 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a  P_IMMUTABLE]..**
231c0 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e         .** </ul>
231d0 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
231e0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
231f0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
23200 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
23210 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
23220 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
23230 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
23240 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
23250 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
23260 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
23270 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
23280 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
23290 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
232a0 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
232b0 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
232c0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
232d0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
232e0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
232f0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
23300 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
23310 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
23320 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
23330 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
23340 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
23350 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
23360 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
23370 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
23380 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
23390 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
233a0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
233b0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
233c0 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
233d0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
233e0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
233f0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
23400 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
23410 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
23420 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
23430 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
23440 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
23450 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
23460 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
23470 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
23480 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
23490 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
234a0 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
234b0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
234c0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
234d0 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
234e0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
234f0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
23500 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
23510 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
23520 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
23530 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
23540 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
23550 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
23560 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
23570 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
23580 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
23590 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
235a0 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
235b0 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
235c0 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
235d0 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
235e0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
235f0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
23600 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
23610 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
23620 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
23630 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
23640 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
23650 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
23660 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
23670 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
23680 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
23690 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
236a0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
236b0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
236c0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
236d0 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
236e0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
236f0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
23700 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
23710 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
23720 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
23730 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
23740 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
23750 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
23760 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
23770 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
23780 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69  b?vfs=unix-dotfi
23790 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  le <td>.**      
237a0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
237b0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
237c0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
237d0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f  ial VFS "unix-do
237e0 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20  tfile".**       
237f0 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74     that uses dot
23800 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20  -files in place 
23810 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72  of posix advisor
23820 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74  y locking..** <t
23830 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
23840 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
23850 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
23860 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
23870 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
23880 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
23890 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
238a0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
238b0 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
238c0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
238d0 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
238e0 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
238f0 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
23900 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
23910 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
23920 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
23930 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
23940 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
23950 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
23960 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
23970 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
23980 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
23990 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
239a0 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
239b0 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
239c0 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
239d0 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
239e0 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
239f0 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
23a00 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
23a10 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
23a20 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
23a30 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
23a40 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
23a50 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
23a60 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
23a70 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
23a80 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
23a90 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
23aa0 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
23ab0 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
23ac0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
23ad0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
23ae0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
23af0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
23b00 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
23b10 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
23b20 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
23b30 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
23b40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23b50 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
23b60 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
23b70 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
23b80 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
23b90 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
23ba0 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
23bb0 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
23bc0 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
23bd0 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
23be0 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
23bf0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
23c00 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
23c10 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
23c20 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
23c30 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
23c40 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
23c50 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
23c60 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
23c70 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
23c80 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
23c90 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
23ca0 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
23cb0 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
23cc0 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
23cd0 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
23ce0 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
23cf0 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
23d00 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
23d10 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
23d20 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ory].*/.int sqli
23d30 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
23d40 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
23d50 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
23d60 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
23d70 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
23d80 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
23d90 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
23da0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
23db0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
23dc0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
23dd0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
23de0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
23df0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
23e00 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
23e10 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
23e20 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
23e30 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
23e40 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
23e50 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
23e60 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
23e70 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
23e80 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
23e90 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
23ea0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
23eb0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
23ec0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
23ed0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
23ee0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
23ef0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
23f00 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
23f10 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
23f20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
23f30 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
23f40 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
23f50 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
23f60 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
23f70 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
23f80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
23f90 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
23fa0 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
23fb0 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
23fc0 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
23fd0 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
23fe0 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
23ff0 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
24000 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
24010 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
24020 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
24030 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
24040 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
24050 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
24060 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
24070 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
24080 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
24090 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
240a0 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
240b0 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
240c0 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
240d0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
240e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
240f0 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
24100 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
24110 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
24120 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
24130 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
24140 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
24150 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
24160 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
24170 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
24180 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
24190 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
241a0 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
241b0 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
241c0 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
241d0 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
241e0 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
241f0 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
24200 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
24210 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
24220 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
24230 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
24240 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
24250 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24260 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
24270 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
24280 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
24290 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
242a0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
242b0 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
242c0 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
242d0 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
242e0 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
242f0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
24300 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
24310 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
24320 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
24330 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
24340 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
24350 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
24360 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
24370 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
24380 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
24390 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
243a0 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
243b0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
243c0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
243d0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
243e0 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
243f0 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
24400 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
24410 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
24420 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
24430 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
24440 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
24450 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
24460 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
24470 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
24480 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
24490 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
244a0 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
244b0 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
244c0 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
244d0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
244e0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
244f0 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
24500 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
24510 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
24520 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
24530 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
24540 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
24550 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
24560 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
24570 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
24580 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
24590 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
245a0 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
245b0 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
245c0 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
245d0 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
245e0 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
245f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
24600 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
24610 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
24620 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
24630 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
24640 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
24650 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
24660 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
24670 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
24680 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
24690 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
246a0 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
246b0 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
246c0 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
246d0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
246e0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
246f0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
24700 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
24710 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
24720 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
24730 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
24740 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
24750 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
24760 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
24770 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  m);.int sqlite3_
24780 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
24790 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
247a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
247b0 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
247c0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
247d0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
247e0 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
247f0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
24800 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
24810 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
24820 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
24830 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
24840 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
24850 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
24860 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
24870 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
24880 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
24890 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
248a0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
248b0 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
248c0 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
248d0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
248e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
248f0 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
24900 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
24910 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
24920 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
24930 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
24940 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
24950 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
24960 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
24970 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
24980 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
24990 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
249a0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
249b0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
249c0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
249d0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
249e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
249f0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
24a00 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
24a10 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
24a20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24a30 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
24a40 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
24a50 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
24a60 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
24a70 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
24a80 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
24a90 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
24aa0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
24ab0 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
24ac0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
24ad0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
24ae0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
24af0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
24b00 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
24b10 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
24b20 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
24b30 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
24b40 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
24b50 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
24b60 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
24b70 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
24b80 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
24b90 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
24ba0 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
24bb0 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
24bc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
24bd0 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
24be0 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
24bf0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
24c00 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
24c10 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
24c20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
24c30 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
24c40 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
24c50 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
24c60 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
24c70 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
24c80 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
24c90 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
24ca0 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
24cb0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
24cc0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
24cd0 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
24ce0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
24cf0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
24d00 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
24d10 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
24d20 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
24d30 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
24d40 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
24d50 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
24d60 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
24d70 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
24d80 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
24d90 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
24da0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
24db0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
24dc0 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
24dd0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
24de0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
24df0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
24e00 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
24e10 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
24e20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
24e30 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
24e40 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
24e50 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
24e60 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
24e70 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
24e80 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
24e90 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
24ea0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
24eb0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
24ec0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
24ed0 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
24ee0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
24ef0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
24f00 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
24f10 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
24f20 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
24f30 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
24f40 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
24f50 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
24f60 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
24f70 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
24f80 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
24f90 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
24fa0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
24fb0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
24fc0 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
24fd0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
24fe0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
24ff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
25000 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
25010 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
25020 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
25030 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
25040 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
25050 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
25060 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63  lite3*);.const c
25070 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
25080 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
25090 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
250a0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
250b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
250c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
250d0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
250e0 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
250f0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
25100 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
25110 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
25120 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
25130 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
25140 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
25150 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
25160 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
25170 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
25180 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
25190 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
251a0 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
251b0 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
251c0 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
251d0 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
251e0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
251f0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
25200 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
25210 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
25220 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
25230 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
25240 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
25250 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
25260 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
25270 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
25280 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
25290 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
252a0 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
252b0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
252c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
252d0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
252e0 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
252f0 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
25300 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
25310 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
25320 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
25330 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
25340 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
25350 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
25360 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
25370 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
25380 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
25390 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
253a0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
253b0 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
253c0 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
253d0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
253e0 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
253f0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
25400 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
25410 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
25420 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
25430 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
25440 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
25450 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
25460 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
25470 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
25480 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
25490 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
254a0 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
254b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
254c0 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
254d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
254e0 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
254f0 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
25500 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
25510 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
25520 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
25530 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
25540 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
25550 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
25560 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
25570 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
25580 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
25590 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
255a0 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
255b0 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
255c0 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
255d0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
255e0 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
255f0 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
25600 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
25610 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
25620 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
25630 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
25640 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
25650 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
25660 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
25670 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
25680 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
25690 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
256a0 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
256b0 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
256c0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
256d0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
256e0 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
256f0 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
25700 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
25710 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
25720 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
25730 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
25740 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
25750 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
25760 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
25770 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
25780 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
25790 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
257a0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
257b0 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
257c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
257d0 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
257e0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
257f0 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
25800 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
25810 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
25820 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
25830 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
25840 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
25850 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
25860 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
25870 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
25880 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
25890 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
258a0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
258b0 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
258c0 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
258d0 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
258e0 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
258f0 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
25900 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
25910 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
25920 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
25930 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
25940 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
25950 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
25960 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
25970 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
25980 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
25990 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
259a0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
259b0 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
259c0 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
259d0 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
259e0 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
259f0 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
25a00 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
25a10 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
25a20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
25a30 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
25a40 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
25a50 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
25a60 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
25a70 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
25a80 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
25a90 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
25aa0 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
25ab0 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
25ac0 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
25ad0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
25ae0 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
25af0 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
25b00 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
25b10 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
25b20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
25b30 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
25b40 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
25b50 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
25b60 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
25b70 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
25b80 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
25b90 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
25ba0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
25bb0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
25bc0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
25bd0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
25be0 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
25bf0 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
25c00 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
25c10 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
25c20 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
25c30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
25c40 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
25c50 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
25c60 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
25c70 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
25c80 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
25c90 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
25ca0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
25cb0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
25cc0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
25cd0 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
25ce0 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
25cf0 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
25d00 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
25d10 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
25d20 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
25d30 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
25d40 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
25d50 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
25d60 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
25d70 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25d80 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
25d90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
25da0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
25db0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
25dc0 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
25dd0 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
25de0 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
25df0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25e00 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
25e10 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
25e20 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
25e30 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
25e40 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
25e50 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
25e60 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
25e70 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25e80 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
25e90 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
25ea0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
25eb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25ec0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25ed0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
25ee0 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
25ef0 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
25f00 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
25f10 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
25f20 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25f30 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
25f40 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
25f50 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
25f60 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
25f70 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25f80 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
25f90 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
25fa0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
25fb0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
25fc0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
25fd0 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
25fe0 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
25ff0 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
26000 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26010 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
26020 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
26030 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
26040 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
26050 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26060 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
26070 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
26080 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
26090 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
260a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
260b0 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
260c0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
260d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
260e0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
260f0 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
26100 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
26110 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
26120 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
26130 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
26140 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
26150 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
26160 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
26170 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
26180 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
26190 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
261a0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
261b0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
261c0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
261d0 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
261e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
261f0 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
26200 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26210 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
26220 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
26230 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
26240 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26250 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
26260 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
26270 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
26280 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
26290 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
262a0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
262b0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
262c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
262d0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
262e0 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
262f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26300 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
26310 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
26320 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
26330 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
26340 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
26350 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
26360 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
26370 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
26380 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
26390 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
263a0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
263b0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
263c0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
263d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
263e0 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
263f0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
26400 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
26410 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
26420 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
26430 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
26440 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
26450 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
26460 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26470 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
26480 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
26490 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
264a0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  [[SQLITE_LIMIT_W
264b0 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20  ORKER_THREADS]] 
264c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
264d0 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
264e0 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
264f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
26500 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f   of auxiliary wo
26510 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61  rker threads tha
26520 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70  t a single.** [p
26530 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26540 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64  t] may start.</d
26550 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
26560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26570 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
26580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26590 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
265a0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
265b0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
265c0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
265d0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
265e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
265f0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
26600 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
26610 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
26620 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
26630 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
26640 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
26650 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
26660 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
26670 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
26680 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
26690 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
266a0 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
266b0 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
266c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
266d0 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
266e0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
266f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
26700 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
26710 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
26720 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
26730 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
26740 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
26750 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26760 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
26770 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
26780 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26790 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20  _WORKER_THREADS 
267a0 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a            11../*
267b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
267c0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
267d0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
267e0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
267f0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
26800 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
26810 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
26820 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
26830 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
26840 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
26850 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
26860 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
26870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
26880 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
26890 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
268a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
268b0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
268c0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
268d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
268e0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
268f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
26900 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
26910 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
26920 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26930 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
26940 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
26950 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
26960 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
26970 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
26980 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
26990 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
269a0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
269b0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
269c0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
269d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
269e0 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
269f0 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
26a00 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26a10 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
26a20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
26a30 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
26a40 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
26a50 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
26a60 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
26a70 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
26a80 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
26a90 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
26aa0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
26ab0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
26ac0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
26ad0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
26ae0 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
26af0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
26b00 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
26b10 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
26b20 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
26b30 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
26b40 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
26b50 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
26b60 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
26b70 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
26b80 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
26b90 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
26ba0 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
26bb0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
26bc0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
26bd0 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
26be0 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
26bf0 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
26c00 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
26c10 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
26c20 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
26c30 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
26c40 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
26c50 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
26c60 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
26c70 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
26c80 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
26c90 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69  tor bytes as thi
26ca0 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66  s saves SQLite f
26cb0 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a  rom having to.**
26cc0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
26cd0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
26ce0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
26cf0 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
26d00 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
26d10 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
26d20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
26d30 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
26d40 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
26d50 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
26d60 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
26d70 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
26d80 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
26d90 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
26da0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
26db0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
26dc0 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
26dd0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
26de0 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
26df0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
26e00 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
26e10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
26e20 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
26e30 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
26e40 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
26e50 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
26e60 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
26e70 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
26e80 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
26e90 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
26ea0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
26eb0 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
26ec0 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
26ed0 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
26ee0 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
26ef0 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
26f00 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
26f10 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
26f20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
26f30 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
26f40 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
26f50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
26f60 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
26f70 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
26f80 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
26f90 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
26fa0 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
26fb0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
26fc0 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
26fd0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
26fe0 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
26ff0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
27000 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
27010 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
27020 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
27030 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
27040 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
27050 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
27060 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
27070 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
27080 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
27090 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
270a0 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
270b0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
270c0 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
270d0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
270e0 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
270f0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
27100 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
27110 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
27120 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
27130 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
27140 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
27150 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
27160 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
27170 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
27180 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
27190 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
271a0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
271b0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
271c0 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
271d0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
271e0 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
271f0 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
27200 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
27210 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
27220 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
27230 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
27240 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
27250 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
27260 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
27270 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
27280 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
27290 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41   run it again. A
272a0 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54  s many as [SQLIT
272b0 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54  E_MAX_SCHEMA_RET
272c0 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77  RY].** retries w
272d0 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65  ill occur before
272e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
272f0 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74  gives up and ret
27300 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a  urns an error..*
27310 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
27320 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
27330 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
27340 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
27350 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
27360 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
27370 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
27380 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
27390 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
273a0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
273b0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
273c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
273d0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
273e0 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
273f0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
27400 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
27410 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
27420 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
27430 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
27440 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27450 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
27460 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
27470 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
27480 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
27490 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
274a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
274b0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
274c0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
274d0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
274e0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
274f0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
27500 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
27510 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
27520 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
27530 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
27540 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
27550 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
27560 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
27570 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
27580 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
27590 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
275a0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
275b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
275c0 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
275d0 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
275e0 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
275f0 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
27600 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
27610 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
27620 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
27630 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
27640 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
27650 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
27660 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
27670 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
27680 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
27690 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
276a0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
276b0 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
276c0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
276d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
276e0 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
276f0 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
27700 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
27710 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
27720 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
27730 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
27740 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
27750 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
27760 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
27770 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
27780 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f  s enabled..** </
27790 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
277a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
277b0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
277c0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
277d0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
277e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
277f0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
27800 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
27810 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
27820 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
27830 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
27840 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27850 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
27860 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
27870 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
27880 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
27890 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
278a0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
278b0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
278c0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
278d0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
278e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
278f0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
27900 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
27910 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
27920 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27930 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
27940 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
27950 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
27960 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
27970 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
27980 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
27990 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
279a0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
279b0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
279c0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
279d0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
279e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
279f0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
27a00 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
27a10 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
27a20 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
27a30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
27a40 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
27a50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
27a60 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
27a70 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
27a80 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
27a90 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
27aa0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
27ab0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
27ac0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
27ad0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
27ae0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
27af0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
27b00 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
27b10 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
27b20 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
27b30 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
27b40 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
27b50 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
27b60 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
27b70 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
27b80 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
27b90 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
27ba0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
27bb0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27bc0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
27bd0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
27be0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
27bf0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
27c00 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
27c10 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
27c20 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
27c30 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
27c40 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
27c50 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
27c60 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
27c70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
27c80 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
27c90 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
27ca0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
27cb0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
27cc0 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
27cd0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
27ce0 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
27cf0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
27d00 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
27d10 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
27d20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
27d30 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
27d40 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
27d50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
27d60 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
27d70 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
27d80 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
27d90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
27da0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
27db0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
27dc0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
27dd0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
27de0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
27df0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27e00 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
27e10 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
27e20 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
27e30 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
27e40 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
27e50 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
27e60 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
27e70 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
27e80 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
27e90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27ea0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
27eb0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
27ec0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
27ed0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
27ee0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
27ef0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
27f00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
27f10 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
27f20 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
27f30 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
27f40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
27f50 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
27f60 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
27f70 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
27f80 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
27f90 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
27fa0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
27fb0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
27fc0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
27fd0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
27fe0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
27ff0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
28000 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28010 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
28020 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
28030 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
28040 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
28050 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
28060 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
28070 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
28080 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
28090 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
280a0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
280b0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
280c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
280d0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
280e0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
280f0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
28100 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
28110 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
28120 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
28130 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
28140 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
28150 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
28160 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
28170 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
28180 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
28190 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
281a0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
281b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
281c0 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
281d0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
281e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
281f0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
28200 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
28210 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
28220 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
28230 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
28240 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
28250 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
28260 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
28270 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
28280 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
28290 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
282a0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
282b0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
282c0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
282d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
282e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
282f0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
28300 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
28310 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
28320 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
28330 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
28340 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28350 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
28360 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
28370 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28380 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
28390 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
283a0 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
283b0 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Reset.**.** ^The
283c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
283d0 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
283e0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
283f0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
28400 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
28410 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
28420 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
28430 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
28440 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
28450 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
28460 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
28470 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
28480 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
28490 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
284a0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
284b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
284c0 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
284d0 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
284e0 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
284f0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
28500 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
28510 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
28520 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
28530 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
28540 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
28550 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
28560 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
28570 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
28580 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
28590 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
285a0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
285b0 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
285c0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
285d0 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
285e0 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
285f0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
28600 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
28610 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
28620 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
28630 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
28640 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
28650 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
28660 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
28670 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
28680 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
28690 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
286a0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
286b0 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
286c0 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
286d0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
286e0 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
286f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
28700 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
28710 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
28720 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
28730 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
28740 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
28750 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28760 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
28770 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
28780 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28790 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
287a0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
287b0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
287c0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
287d0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
287e0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
287f0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
28800 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
28810 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
28820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28830 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
28840 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
28850 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
28860 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
28870 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
28880 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
28890 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
288a0 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
288b0 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
288c0 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
288d0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
288e0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
288f0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
28900 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
28910 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
28920 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
28930 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
28940 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
28950 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
28960 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
28970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
28980 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
28990 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
289a0 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
289b0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
289c0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
289d0 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
289e0 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
289f0 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
28a00 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
28a10 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
28a20 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
28a30 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
28a40 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
28a50 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28a60 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
28a70 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
28a80 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
28a90 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28aa0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
28ab0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
28ac0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
28ad0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
28ae0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
28af0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
28b00 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
28b10 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
28b20 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
28b30 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
28b40 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
28b50 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
28b60 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
28b70 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
28b80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
28b90 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
28ba0 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
28bb0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
28bc0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
28bd0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
28be0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28bf0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
28c00 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
28c10 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
28c20 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
28c30 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
28c40 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
28c50 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
28c60 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
28c70 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
28c80 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
28c90 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
28ca0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
28cb0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
28cc0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
28cd0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
28ce0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28cf0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
28d00 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
28d10 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
28d20 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
28d30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
28d40 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
28d50 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
28d60 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
28d70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28d80 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
28d90 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
28da0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
28db0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
28dc0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
28dd0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28de0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
28df0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
28e00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
28e10 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
28e20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
28e30 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
28e40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
28e50 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
28e60 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
28e70 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
28e80 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
28e90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28ea0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
28eb0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
28ec0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
28ed0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28ee0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
28ef0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
28f00 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
28f10 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
28f20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
28f30 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
28f40 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
28f50 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
28f60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
28f70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
28f80 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
28f90 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
28fa0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
28fb0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
28fc0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
28fd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
28fe0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
28ff0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
29000 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
29010 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
29020 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
29030 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
29040 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
29050 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
29060 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29070 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
29080 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
29090 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
290a0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
290b0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
290c0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
290d0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
290e0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
290f0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
29100 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
29110 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
29120 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
29130 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
29140 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
29150 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
29160 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
29170 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
29180 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
29190 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
291a0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
291b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
291c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
291d0 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
291e0 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
291f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
29200 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
29210 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29220 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
29230 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
29240 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
29250 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
29260 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
29270 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
29280 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
29290 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
292a0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
292b0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
292c0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
292d0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
292e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
292f0 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
29300 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
29310 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
29320 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
29330 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
29340 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
29350 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
29360 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
29370 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
29380 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
29390 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
293a0 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
293b0 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
293c0 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
293d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
293e0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
293f0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
29400 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
29410 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
29420 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
29430 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
29440 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
29450 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
29460 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
29470 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
29480 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29490 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
294a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
294b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
294c0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
294d0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
294e0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
294f0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
29500 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
29510 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
29520 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
29530 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
29540 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
29550 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
29560 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
29570 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
29580 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
29590 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
295a0 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
295b0 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
295c0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
295d0 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
295e0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
295f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29600 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
29610 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
29620 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
29630 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
29640 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
29650 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
29660 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
29670 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
29680 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
29690 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
296a0 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
296b0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
296c0 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
296d0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
296e0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
296f0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
29700 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
29710 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
29720 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
29730 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
29740 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
29750 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29760 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  16().** or sqlit
29770 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
29780 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29790 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
297a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73   parameter.** is
297b0 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65   ignored and the
297c0 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74   end result is t
297d0 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74  he same as sqlit
297e0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a  e3_bind_null()..
297f0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
29800 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
29810 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
29820 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
29830 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
29840 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
29850 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
29860 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
29870 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
29880 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
29890 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
298a0 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
298b0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
298c0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
298d0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
298e0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
298f0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
29900 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
29910 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
29920 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
29930 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
29940 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
29950 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
29960 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
29970 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
29980 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29990 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
299a0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
299b0 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
299c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
299d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
299e0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
299f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
29a00 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
29a10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29a20 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
29a30 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
29a40 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
29a50 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a  text64() then.**
29a60 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
29a70 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
29a80 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
29a90 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
29aa0 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
29ab0 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
29ac0 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
29ad0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
29ae0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
29af0 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
29b00 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
29b10 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
29b20 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
29b30 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
29b40 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
29b50 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
29b60 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
29b70 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
29b80 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
29b90 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
29ba0 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
29bb0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
29bc0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
29bd0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
29be0 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61  nt to the BLOB a
29bf0 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e  nd string bindin
29c00 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  g interfaces.** 
29c10 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
29c20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
29c30 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
29c40 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
29c50 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
29c60 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
29c70 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
29c80 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
29c90 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
29ca0 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
29cb0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62  if the call to b
29cc0 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a  ind API fails..*
29cd0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
29ce0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
29cf0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
29d00 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
29d10 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
29d20 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
29d30 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
29d40 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
29d50 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
29d60 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
29d70 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
29d80 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
29d90 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
29da0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
29db0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
29dc0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
29dd0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
29de0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
29df0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
29e00 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
29e10 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
29e20 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
29e30 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d  ^The sixth argum
29e40 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
29e50 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73  ind_text64() mus
29e60 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b  t be one of.** [
29e70 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
29e80 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53  QLITE_UTF16], [S
29e90 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
29ea0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
29eb0 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66  LE].** to specif
29ec0 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  y the encoding o
29ed0 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68  f the text in th
29ee0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
29ef0 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69  r.  If.** the si
29f00 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
29f10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29f20 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  t64() is not one
29f30 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77   of the.** allow
29f40 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20  ed values shown 
29f50 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65  above, or if the
29f60 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69   text encoding i
29f70 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66  s different.** f
29f80 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  rom the encoding
29f90 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
29fa0 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  e sixth paramete
29fb0 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  r, then the beha
29fc0 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66  vior.** is undef
29fd0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
29fe0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
29ff0 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
2a000 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
2a010 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
2a020 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
2a030 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
2a040 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
2a050 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
2a060 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
2a070 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
2a080 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
2a090 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
2a0a0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
2a0b0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
2a0c0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
2a0d0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
2a0e0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
2a0f0 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
2a100 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
2a110 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
2a120 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
2a130 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
2a140 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
2a150 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
2a160 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
2a170 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
2a180 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
2a190 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
2a1a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2a1b0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2a1c0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
2a1d0 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
2a1e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2a1f0 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
2a200 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a210 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
2a220 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a230 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
2a240 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
2a250 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
2a260 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
2a270 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
2a280 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
2a290 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
2a2a0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
2a2b0 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
2a2c0 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
2a2d0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2a2e0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2a2f0 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
2a300 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
2a310 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
2a320 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
2a330 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
2a340 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
2a350 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
2a360 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
2a370 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
2a380 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
2a390 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2a3a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
2a3b0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2a3c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2a3d0 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
2a3e0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
2a3f0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
2a400 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
2a410 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62  _TOOBIG] might b
2a420 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
2a430 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69  e size of a stri
2a440 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78  ng or BLOB.** ex
2a450 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70  ceeds limits imp
2a460 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
2a470 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2a480 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f  LIMIT_LENGTH]) o
2a490 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  r.** [SQLITE_MAX
2a4a0 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53  _LENGTH]..** ^[S
2a4b0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
2a4c0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2a4d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
2a4e0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2a4f0 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
2a500 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
2a510 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
2a520 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
2a530 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2a540 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2a550 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2a560 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a570 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
2a580 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a590 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2a5a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2a5b0 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
2a5c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2a5d0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
2a5e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2a5f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2a600 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  nd_blob64(sqlite
2a610 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2a620 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74  nst void*, sqlit
2a630 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2a640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a650 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2a660 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2a670 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
2a680 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2a690 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
2a6a0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
2a6b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a6c0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
2a6d0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
2a6e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a6f0 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
2a700 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2a710 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
2a720 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
2a730 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2a740 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2a750 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
2a760 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  *,int,void(*)(vo
2a770 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2a780 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
2a790 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a7a0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2a7b0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2a7c0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2a7d0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71  3_bind_text64(sq
2a7e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a7f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
2a800 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2a810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a820 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
2a830 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64  void*), unsigned
2a840 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b   char encoding);
2a850 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2a860 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
2a870 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2a880 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
2a890 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2a8a0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
2a8b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2a8c0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
2a8d0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2a8e0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
2a8f0 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
2a900 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
2a910 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
2a920 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
2a930 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
2a940 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a950 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
2a960 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
2a970 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
2a980 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
2a990 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
2a9a0 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
2a9b0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
2a9c0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
2a9d0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
2a9e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2a9f0 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
2aa00 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
2aa10 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
2aa20 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2aa30 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
2aa40 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
2aa50 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
2aa60 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
2aa70 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
2aa80 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
2aa90 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
2aaa0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
2aab0 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
2aac0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
2aad0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2aae0 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
2aaf0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
2ab00 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
2ab10 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
2ab20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2ab30 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2ab40 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2ab50 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2ab60 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2ab70 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2ab80 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ab90 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2aba0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2abb0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2abc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2abd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2abe0 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
2abf0 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
2ac00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2ac10 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2ac20 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
2ac30 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2ac40 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
2ac50 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
2ac60 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
2ac70 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2ac80 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
2ac90 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2aca0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2acb0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2acc0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
2acd0 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
2ace0 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
2acf0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2ad00 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
2ad10 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2ad20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2ad30 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
2ad40 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
2ad50 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
2ad60 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
2ad70 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
2ad80 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2ad90 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
2ada0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
2adb0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
2adc0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
2add0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
2ade0 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
2adf0 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
2ae00 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
2ae10 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
2ae20 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2ae30 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
2ae40 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
2ae50 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
2ae60 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
2ae70 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
2ae80 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
2ae90 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2aea0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
2aeb0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
2aec0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
2aed0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
2aee0 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
2aef0 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
2af00 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
2af10 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
2af20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2af30 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2af40 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2af50 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2af60 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2af70 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2af80 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2af90 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2afa0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2afb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2afc0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2afd0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
2afe0 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
2aff0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2b000 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b010 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2b020 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
2b030 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
2b040 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a  A Given Name.**.
2b050 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2b060 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2b070 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2b080 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2b090 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2b0a0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2b0b0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2b0c0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2b0d0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2b0e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2b0f0 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2b100 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2b110 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2b120 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2b130 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2b140 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2b150 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2b160 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2b170 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2b180 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2b190 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2b1a0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2b1b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b1c0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2b1d0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2b1e0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2b1f0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2b200 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b210 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2b220 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2b230 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2b240 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2b250 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b260 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
2b270 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
2b280 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
2b290 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b2a0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
2b2b0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
2b2c0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
2b2d0 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
2b2e0 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
2b2f0 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
2b300 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
2b310 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
2b320 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b330 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
2b340 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2b350 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
2b360 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
2b370 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
2b380 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
2b390 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
2b3a0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2b3b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2b3c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b3d0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
2b3e0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
2b3f0 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  Set.**.** ^Retur
2b400 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2b410 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2b420 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
2b430 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
2b440 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b450 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
2b460 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
2b470 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
2b480 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
2b490 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
2b4a0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
2b4b0 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
2b4c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2b4d0 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
2b4e0 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
2b4f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2b500 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2b510 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2b520 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
2b530 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
2b540 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
2b550 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2b560 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
2b570 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
2b580 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
2b590 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2b5a0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2b5b0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
2b5c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b5d0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
2b5e0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2b5f0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2b600 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2b610 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
2b620 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2b630 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
2b640 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2b650 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2b660 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2b670 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2b680 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
2b690 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b6a0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
2b6b0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
2b6c0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
2b6d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2b6e0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
2b6f0 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
2b700 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2b710 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
2b720 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
2b730 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
2b740 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
2b750 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
2b760 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b770 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
2b780 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2b790 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2b7a0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2b7b0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2b7c0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2b7d0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2b7e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2b7f0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2b800 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2b810 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
2b820 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2b830 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
2b840 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2b850 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
2b860 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
2b870 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
2b880 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
2b890 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
2b8a0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
2b8b0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
2b8c0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
2b8d0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2b8e0 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
2b8f0 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
2b900 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2b910 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2b920 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
2b930 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
2b940 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
2b950 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
2b960 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
2b970 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
2b980 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
2b990 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
2b9a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
2b9b0 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
2b9c0 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
2b9d0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
2b9e0 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
2b9f0 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
2ba00 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73  he next..*/.cons
2ba10 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2ba20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
2ba30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2ba40 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2ba50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2ba60 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2ba70 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2ba80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2ba90 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2baa0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2bab0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2bac0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
2bad0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
2bae0 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
2baf0 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
2bb00 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
2bb10 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
2bb20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
2bb30 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
2bb40 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2bb50 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
2bb60 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2bb70 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
2bb80 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
2bb90 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
2bba0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
2bbb0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2bbc0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
2bbd0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
2bbe0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
2bbf0 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
2bc00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2bc10 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
2bc20 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
2bc30 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2bc40 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
2bc50 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
2bc60 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
2bc70 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
2bc80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bc90 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
2bca0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2bcb0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2bcc0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2bcd0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2bce0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2bcf0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2bd00 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2bd10 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2bd20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2bd30 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
2bd40 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
2bd50 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
2bd60 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
2bd70 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
2bd80 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
2bd90 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
2bda0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
2bdb0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
2bdc0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
2bdd0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
2bde0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2bdf0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2be00 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2be10 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2be20 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
2be30 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2be40 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2be50 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
2be60 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
2be70 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
2be80 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
2be90 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
2bea0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
2beb0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
2bec0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
2bed0 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
2bee0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
2bef0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
2bf00 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2bf10 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
2bf20 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
2bf30 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
2bf40 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
2bf50 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
2bf60 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
2bf70 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
2bf80 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
2bf90 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
2bfa0 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
2bfb0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2bfc0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
2bfd0 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
2bfe0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
2bff0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2c000 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2c010 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
2c020 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
2c030 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
2c040 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
2c050 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
2c060 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
2c070 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
2c080 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
2c090 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
2c0a0 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
2c0b0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
2c0c0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
2c0d0 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
2c0e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
2c0f0 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
2c100 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2c110 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2c120 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2c130 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2c140 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2c150 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2c160 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
2c170 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2c180 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2c190 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
2c1a0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
2c1b0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
2c1c0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
2c1d0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
2c1e0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2c1f0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
2c200 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2c210 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2c220 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2c230 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
2c240 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2c250 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
2c260 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
2c270 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
2c280 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
2c290 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
2c2a0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
2c2b0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
2c2c0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2c2d0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2c2e0 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
2c2f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c300 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
2c310 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c320 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2c330 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2c340 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
2c350 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2c360 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2c370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2c380 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
2c390 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2c3a0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2c3b0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2c3c0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2c3d0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
2c3e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2c3f0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
2c400 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c410 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2c420 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2c430 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
2c440 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2c450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c460 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
2c470 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
2c480 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  sult.**.** ^(The
2c490 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2c4a0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2c4b0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2c4c0 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
2c4d0 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
2c4e0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
2c4f0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2c500 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
2c510 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
2c520 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
2c530 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
2c540 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
2c550 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
2c560 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
2c570 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
2c580 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
2c590 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
2c5a0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2c5b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2c5c0 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
2c5d0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2c5e0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
2c5f0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2c600 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
2c610 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2c620 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
2c630 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
2c640 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
2c650 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2c660 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
2c670 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
2c680 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
2c690 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
2c6a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
2c6b0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
2c6c0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
2c6d0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
2c6e0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
2c6f0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
2c700 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
2c710 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
2c720 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
2c730 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
2c740 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
2c750 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
2c760 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
2c770 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2c780 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
2c790 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
2c7a0 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
2c7b0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
2c7c0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
2c7d0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
2c7e0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
2c7f0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
2c800 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
2c810 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
2c820 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2c830 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
2c840 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
2c850 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
2c860 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
2c870 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
2c880 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
2c890 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
2c8a0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
2c8b0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
2c8c0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
2c8d0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
2c8e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2c8f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2c900 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2c910 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2c920 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2c930 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
2c940 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2c950 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c960 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
2c970 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
2c980 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
2c990 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c9a0 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
2c9b0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
2c9c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c9d0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2c9e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2c9f0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
2ca00 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2ca10 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
2ca20 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
2ca30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ca40 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
2ca50 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
2ca60 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
2ca70 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
2ca80 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
2ca90 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
2caa0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
2cab0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
2cac0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
2cad0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
2cae0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
2caf0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
2cb00 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
2cb10 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
2cb20 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
2cb30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2cb40 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2cb50 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
2cb60 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
2cb70 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
2cb80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2cb90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2cba0 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
2cbb0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
2cbc0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
2cbd0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2cbe0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
2cbf0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
2cc00 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2cc10 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
2cc20 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
2cc30 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
2cc40 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2cc50 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2cc60 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
2cc70 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
2cc80 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
2cc90 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
2cca0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
2ccb0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
2ccc0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2ccd0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
2cce0 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
2ccf0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
2cd00 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2cd10 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
2cd20 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2cd30 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
2cd40 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
2cd50 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
2cd60 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
2cd70 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
2cd80 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
2cd90 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
2cda0 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
2cdb0 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
2cdc0 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
2cdd0 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
2cde0 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
2cdf0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2ce00 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
2ce10 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
2ce20 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
2ce30 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
2ce40 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
2ce50 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
2ce60 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
2ce70 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
2ce80 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
2ce90 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
2cea0 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
2ceb0 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
2cec0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
2ced0 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
2cee0 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
2cef0 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
2cf00 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
2cf10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2cf20 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2cf30 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
2cf40 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2cf50 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
2cf60 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
2cf70 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
2cf80 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
2cf90 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
2cfa0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2cfb0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
2cfc0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2cfd0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
2cfe0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
2cff0 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
2d000 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
2d010 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
2d020 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
2d030 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
2d040 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
2d050 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
2d060 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
2d070 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
2d080 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2d090 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
2d0a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
2d0b0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
2d0c0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
2d0d0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
2d0e0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
2d0f0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
2d100 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
2d110 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
2d120 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
2d130 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
2d140 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
2d150 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2d160 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2d170 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
2d180 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
2d190 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
2d1a0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
2d1b0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
2d1c0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
2d1d0 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
2d1e0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2d1f0 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
2d200 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2d210 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
2d220 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
2d230 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
2d240 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
2d250 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
2d260 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2d270 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
2d280 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2d290 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
2d2a0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2d2b0 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
2d2c0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2d2d0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
2d2e0 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
2d2f0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
2d300 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2d310 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
2d320 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
2d330 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
2d340 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
2d350 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
2d360 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2d370 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2d380 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
2d390 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
2d3a0 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2d3b0 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
2d3c0 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
2d3d0 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
2d3e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
2d3f0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
2d400 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
2d410 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
2d420 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2d430 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
2d440 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
2d450 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
2d460 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
2d470 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
2d480 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
2d490 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2d4a0 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
2d4b0 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
2d4c0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2d4d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
2d4e0 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
2d4f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2d500 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
2d510 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
2d520 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
2d530 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
2d540 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
2d550 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2d560 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
2d570 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2d580 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
2d590 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2d5a0 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
2d5b0 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
2d5c0 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
2d5d0 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
2d5e0 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
2d5f0 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e  after version 3.
2d600 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
2d610 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
2d620 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2d630 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
2d640 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
2d650 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
2d660 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
2d670 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
2d680 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
2d690 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
2d6a0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
2d6b0 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
2d6c0 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
2d6d0 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
2d6e0 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
2d6f0 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
2d700 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
2d710 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
2d720 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
2d730 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
2d740 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
2d750 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
2d760 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
2d770 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
2d780 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
2d790 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
2d7a0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2d7b0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
2d7c0 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
2d7d0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
2d7e0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
2d7f0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2d800 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
2d810 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
2d820 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
2d830 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
2d840 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
2d850 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
2d860 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2d870 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d880 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
2d890 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
2d8a0 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
2d8b0 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
2d8c0 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
2d8d0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
2d8e0 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
2d8f0 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
2d900 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
2d910 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
2d920 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
2d930 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
2d940 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
2d950 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
2d960 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
2d970 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2d980 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2d990 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d9a0 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
2d9b0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
2d9c0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
2d9d0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2d9e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2d9f0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
2da00 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
2da10 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2da20 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
2da30 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
2da40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2da50 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2da60 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2da70 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
2da80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
2da90 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
2daa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2dab0 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
2dac0 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
2dad0 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t set.**.** ^The
2dae0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2daf0 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
2db00 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2db10 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2db20 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
2db30 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2db40 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
2db50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2db60 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
2db70 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
2db80 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
2db90 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
2dba0 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
2dbb0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
2dbc0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
2dbd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
2dbe0 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
2dbf0 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
2dc00 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2dc10 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
2dc20 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2dc30 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2dc40 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
2dc50 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
2dc60 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
2dc70 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2dc80 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
2dc90 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
2dca0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
2dcb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2dcc0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
2dcd0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
2dce0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2dcf0 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
2dd00 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
2dd10 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
2dd20 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2dd30 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
2dd40 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
2dd50 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
2dd60 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
2dd70 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
2dd80 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
2dd90 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
2dda0 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
2ddb0 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
2ddc0 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
2ddd0 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
2dde0 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
2ddf0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2de00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2de10 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
2de20 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2de30 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2de40 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2de50 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
2de60 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
2de70 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
2de80 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
2de90 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
2dea0 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
2deb0 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
2dec0 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
2ded0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2dee0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2def0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
2df00 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
2df10 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
2df20 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
2df30 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
2df40 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
2df50 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
2df60 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
2df70 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
2df80 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
2df90 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
2dfa0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
2dfb0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
2dfc0 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
2dfd0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
2dfe0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
2dff0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
2e000 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
2e010 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
2e020 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
2e030 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
2e040 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
2e050 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
2e060 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
2e070 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
2e080 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
2e090 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2e0a0 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
2e0b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
2e0c0 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
2e0d0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
2e0e0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
2e0f0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
2e100 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
2e110 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
2e120 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
2e130 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
2e140 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
2e150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2e160 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
2e170 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
2e180 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
2e190 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
2e1a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2e1b0 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
2e1c0 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66  sult set" interf
2e1d0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ace..**.** ^Thes
2e1e0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2e1f0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
2e200 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
2e210 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
2e220 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
2e230 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
2e240 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
2e250 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2e260 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
2e270 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
2e280 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2e290 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
2e2a0 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
2e2b0 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
2e2c0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
2e2d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
2e2e0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
2e2f0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
2e300 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
2e310 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2e320 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2e330 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
2e340 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
2e350 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
2e360 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
2e370 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
2e380 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
2e390 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
2e3a0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
2e3b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2e3c0 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
2e3d0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
2e3e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e3f0 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
2e400 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2e410 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
2e420 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
2e430 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
2e440 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
2e450 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
2e460 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
2e470 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2e480 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
2e490 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
2e4a0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
2e4b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2e4c0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2e4d0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2e4e0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2e4f0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
2e500 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e510 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
2e520 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
2e530 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
2e540 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
2e550 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2e560 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2e570 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
2e580 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2e590 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2e5a0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
2e5b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2e5c0 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
2e5d0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
2e5e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2e5f0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
2e600 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
2e610 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
2e620 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2e630 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2e640 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2e650 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
2e660 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
2e670 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
2e680 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2e690 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
2e6a0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
2e6b0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2e6c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2e6d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2e6e0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
2e6f0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
2e700 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2e710 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
2e720 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
2e730 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
2e740 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
2e750 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
2e760 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
2e770 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
2e780 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
2e790 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
2e7a0 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
2e7b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
2e7c0 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
2e7d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2e7e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2e7f0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
2e800 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
2e810 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
2e820 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
2e830 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
2e840 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
2e850 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
2e860 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
2e870 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2e880 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
2e890 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
2e8a0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
2e8b0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
2e8c0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
2e8d0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
2e8e0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
2e8f0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
2e900 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
2e910 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2e920 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
2e930 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2e940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e950 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
2e960 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2e970 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2e980 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2e990 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2e9a0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2e9b0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
2e9c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e9d0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
2e9e0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2e9f0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
2ea00 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2ea10 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2ea20 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2ea30 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2ea40 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2ea50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
2ea60 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2ea70 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2ea80 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2ea90 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
2eaa0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2eab0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2eac0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2ead0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2eae0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2eaf0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2eb00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
2eb10 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2eb20 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2eb30 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2eb40 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
2eb50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2eb60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
2eb70 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2eb80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2eb90 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2eba0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2ebb0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2ebc0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
2ebd0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2ebe0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2ebf0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2ec00 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
2ec10 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2ec20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2ec30 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2ec40 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2ec50 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2ec60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ec70 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
2ec80 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2ec90 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2eca0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2ecb0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2ecc0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2ecd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2ece0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2ecf0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2ed00 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2ed10 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2ed20 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
2ed30 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2ed40 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
2ed50 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2ed60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2ed70 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
2ed80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2ed90 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
2eda0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
2edb0 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
2edc0 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
2edd0 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
2ede0 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
2edf0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2ee00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ee10 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
2ee20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ee30 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
2ee40 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
2ee50 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
2ee60 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2ee70 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
2ee80 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
2ee90 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2eea0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
2eeb0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2eec0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
2eed0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
2eee0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
2eef0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
2ef00 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
2ef10 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
2ef20 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2ef30 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
2ef40 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
2ef50 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2ef60 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
2ef70 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2ef80 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2ef90 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
2efa0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2efb0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
2efc0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2efd0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2efe0 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
2eff0 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
2f000 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2f010 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2f020 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
2f030 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
2f040 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2f050 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
2f060 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2f070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2f080 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
2f090 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
2f0a0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
2f0b0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
2f0c0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
2f0d0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
2f0e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2f0f0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2f100 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
2f110 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2f120 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2f130 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2f140 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
2f150 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
2f160 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
2f170 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
2f180 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
2f190 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
2f1a0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
2f1b0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
2f1c0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
2f1d0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
2f1e0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
2f1f0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
2f200 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
2f210 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
2f220 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
2f230 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
2f240 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
2f250 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
2f260 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
2f270 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
2f280 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
2f290 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
2f2a0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
2f2b0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
2f2c0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
2f2d0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
2f2e0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2f2f0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2f300 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2f310 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2f320 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
2f330 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
2f340 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
2f350 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2f360 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2f370 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
2f380 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2f390 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2f3a0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2f3b0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
2f3c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2f3d0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2f3e0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2f3f0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2f400 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
2f410 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2f420 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2f430 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2f440 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2f450 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
2f460 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2f470 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2f480 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
2f490 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
2f4a0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2f4b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2f4c0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
2f4d0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
2f4e0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2f4f0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2f500 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2f510 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
2f520 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2f530 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2f540 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42  <td> [CAST] to B
2f550 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  LOB.** <tr><td> 
2f560 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
2f570 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
2f580 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
2f590 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2f5a0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2f5b0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2f5c0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
2f5d0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2f5e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2f5f0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
2f600 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2f610 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2f620 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
2f630 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
2f640 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2f650 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
2f660 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
2f670 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2f680 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2f690 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
2f6a0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
2f6b0 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
2f6c0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
2f6d0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  e>)^.**.** The t
2f6e0 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
2f6f0 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
2f700 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
2f710 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
2f720 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
2f730 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
2f740 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
2f750 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
2f760 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
2f770 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
2f780 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
2f790 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
2f7a0 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
2f7b0 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
2f7c0 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
2f7d0 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
2f7e0 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
2f7f0 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
2f800 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
2f810 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
2f820 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
2f830 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
2f840 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
2f850 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2f860 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2f870 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
2f880 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
2f890 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2f8a0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
2f8b0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
2f8c0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
2f8d0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
2f8e0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
2f8f0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
2f900 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
2f910 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
2f920 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2f930 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2f940 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
2f950 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2f960 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2f970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2f980 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2f990 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
2f9a0 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
2f9b0 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
2f9c0 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
2f9d0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2f9e0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2f9f0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
2fa00 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2fa10 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
2fa20 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2fa30 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2fa40 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2fa50 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2fa60 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2fa70 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
2fa80 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2fa90 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2faa0 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
2fab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fac0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
2fad0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2fae0 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
2faf0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2fb00 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2fb10 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2fb20 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
2fb30 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
2fb40 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
2fb50 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
2fb60 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
2fb70 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
2fb80 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
2fb90 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
2fba0 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
2fbb0 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
2fbc0 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
2fbd0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
2fbe0 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
2fbf0 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
2fc00 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
2fc10 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
2fc20 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
2fc30 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
2fc40 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
2fc50 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
2fc60 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
2fc70 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
2fc80 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
2fc90 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
2fca0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2fcb0 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
2fcc0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
2fcd0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
2fce0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
2fcf0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
2fd00 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
2fd10 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
2fd20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
2fd30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2fd40 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
2fd50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fd60 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2fd70 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2fd80 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
2fd90 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2fda0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2fdb0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2fdc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2fdd0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2fde0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fdf0 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
2fe00 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
2fe10 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
2fe20 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
2fe30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2fe40 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
2fe50 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
2fe60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2fe70 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
2fe80 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
2fe90 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
2fea0 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
2feb0 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
2fec0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2fed0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2fee0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
2fef0 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
2ff00 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
2ff10 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
2ff20 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
2ff30 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
2ff40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ff50 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
2ff60 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2ff70 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
2ff80 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
2ff90 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2ffa0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2ffb0 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
2ffc0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2ffd0 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
2ffe0 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
2fff0 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
30000 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
30010 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
30020 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
30030 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
30040 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
30050 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
30060 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
30070 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
30080 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
30090 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
300a0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
300b0 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
300c0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
300d0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
300e0 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
300f0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
30100 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
30110 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30120 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
30130 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
30140 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
30150 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
30160 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
30170 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
30180 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
30190 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
301a0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
301b0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
301c0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
301d0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
301e0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
301f0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
30200 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
30210 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
30220 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
30230 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
30240 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
30250 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
30260 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
30270 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
30280 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
30290 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
302a0 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
302b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
302c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
302d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
302e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
302f0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
30300 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
30310 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30320 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
30330 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
30340 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
30350 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
30360 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
30370 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
30380 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30390 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
303a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
303b0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
303c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
303d0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
303e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
303f0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
30400 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30410 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
30420 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30430 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
30440 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
30450 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
30460 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
30470 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30480 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
30490 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
304a0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
304b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
304c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
304d0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
304e0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
304f0 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
30500 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30510 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
30520 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
30530 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30540 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
30550 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
30560 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
30570 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
30580 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
30590 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
305a0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
305b0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
305c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
305d0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
305e0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
305f0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
30600 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
30610 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
30620 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
30630 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
30640 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
30650 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
30660 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
30670 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
30680 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
30690 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
306a0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
306b0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
306c0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
306d0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
306e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
306f0 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
30700 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
30710 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
30720 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
30730 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
30740 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30750 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
30760 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
30770 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
30780 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
30790 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
307a0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
307b0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
307c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
307d0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
307e0 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
307f0 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
30800 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
30810 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
30820 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
30830 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
30840 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
30850 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
30860 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
30870 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
30880 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
30890 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
308a0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
308b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
308c0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
308d0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
308e0 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
308f0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
30900 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
30910 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
30920 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
30930 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
30940 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
30950 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
30960 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
30970 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
30980 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
30990 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
309a0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
309b0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
309c0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
309d0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
309e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
309f0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
30a00 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
30a10 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
30a20 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
30a30 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
30a40 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
30a50 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
30a60 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
30a70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
30a80 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
30a90 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
30aa0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
30ab0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
30ac0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
30ad0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
30ae0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
30af0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
30b00 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
30b10 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
30b20 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
30b30 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
30b40 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
30b50 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
30b60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30b70 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
30b80 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
30b90 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
30ba0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
30bb0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
30bc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
30bd0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
30be0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30bf0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
30c00 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
30c10 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
30c20 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
30c30 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
30c40 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
30c50 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
30c60 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
30c70 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
30c80 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
30c90 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
30ca0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
30cb0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
30cc0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
30cd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
30ce0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
30cf0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
30d00 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
30d10 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
30d20 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
30d30 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
30d40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
30d50 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
30d60 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
30d70 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
30d80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
30d90 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
30da0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
30db0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
30dc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
30dd0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
30de0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
30df0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
30e00 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
30e10 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
30e20 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
30e30 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
30e40 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
30e50 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
30e60 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
30e70 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
30e80 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
30e90 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
30ea0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
30eb0 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
30ec0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
30ed0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
30ee0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
30ef0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
30f00 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
30f10 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
30f20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
30f30 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
30f40 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
30f50 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
30f60 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
30f70 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
30f80 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
30f90 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
30fa0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
30fb0 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
30fc0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
30fd0 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
30fe0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
30ff0 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
31000 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
31010 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
31020 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
31030 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
31040 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
31050 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
31060 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
31070 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
31080 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31090 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
310a0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
310b0 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
310c0 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
310d0 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
310e0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
310f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
31100 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31110 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
31120 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
31130 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
31140 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
31150 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
31160 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
31170 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
31180 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
31190 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
311a0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
311b0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
311c0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
311d0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
311e0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
311f0 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
31200 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
31210 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
31220 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
31230 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
31240 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
31250 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
31260 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
31270 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
31280 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
31290 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
312a0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
312b0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
312c0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
312d0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
312e0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
312f0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
31300 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
31310 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
31320 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
31330 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
31340 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
31350 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
31360 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
31370 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
31380 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
31390 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
313a0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
313b0 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
313c0 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
313d0 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
313e0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
313f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
31400 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
31410 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
31420 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
31430 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
31440 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
31450 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
31460 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
31470 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
31480 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
31490 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
314a0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
314b0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
314c0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
314d0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
314e0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
314f0 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
31500 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
31510 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
31520 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
31530 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
31540 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
31550 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
31560 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
31570 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
31580 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
31590 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
315a0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
315b0 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
315c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
315d0 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
315e0 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
315f0 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
31600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31610 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
31620 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
31630 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
31640 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
31650 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
31660 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
31670 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
31680 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
31690 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
316a0 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
316b0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
316c0 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
316d0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
316e0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
316f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
31700 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
31710 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
31720 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
31730 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
31740 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
31750 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
31760 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
31770 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
31780 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
31790 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
317a0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
317b0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
317c0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
317d0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
317e0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
317f0 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
31800 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
31810 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
31820 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
31830 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
31840 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
31850 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
31860 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
31870 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
31880 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
31890 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
318a0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
318b0 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
318c0 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
318d0 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
318e0 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
318f0 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
31900 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
31910 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
31920 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
31930 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
31940 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
31950 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
31960 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
31970 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
31980 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
31990 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
319a0 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
319b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
319c0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
319d0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
319e0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
319f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
31a00 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
31a10 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
31a20 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
31a30 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
31a40 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
31a50 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
31a60 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
31a70 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
31a80 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
31a90 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
31aa0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
31ab0 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
31ac0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
31ad0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
31ae0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
31af0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
31b00 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
31b10 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
31b20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
31b30 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
31b40 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
31b50 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
31b60 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
31b70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
31b80 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
31b90 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
31ba0 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
31bb0 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
31bc0 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
31bd0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
31be0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
31bf0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
31c00 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
31c10 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
31c20 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
31c30 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
31c40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
31c50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31c60 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
31c70 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
31c80 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
31c90 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
31ca0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
31cb0 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
31cc0 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
31cd0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
31ce0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
31cf0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
31d00 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
31d10 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
31d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
31d30 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
31d40 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
31d50 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
31d60 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
31d70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31d80 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
31d90 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
31da0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
31db0 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
31dc0 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
31dd0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
31de0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
31df0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
31e00 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
31e10 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
31e20 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
31e30 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
31e40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
31e50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31e60 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
31e70 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
31e80 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
31e90 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
31ea0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
31eb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
31ec0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
31ed0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
31ee0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
31ef0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
31f00 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
31f10 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
31f20 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
31f30 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
31f40 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
31f50 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
31f60 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
31f70 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
31f80 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
31f90 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
31fa0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
31fb0 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
31fc0 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
31fd0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
31fe0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
31ff0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
32000 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
32010 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
32020 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
32030 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
32040 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
32050 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
32060 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
32070 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
32080 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
32090 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
320a0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
320b0 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
320c0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
320d0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
320e0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
320f0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
32100 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
32110 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
32120 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
32130 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
32140 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
32150 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
32160 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
32170 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
32180 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
32190 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
321a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
321b0 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
321c0 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
321d0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
321e0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
321f0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
32200 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
32210 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
32220 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
32230 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
32240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32250 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
32260 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
32270 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
32280 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
32290 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
322a0 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
322b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
322c0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
322d0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
322e0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
322f0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
32300 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
32310 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
32320 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
32330 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
32340 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
32350 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
32360 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
32370 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32380 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32390 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
323a0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
323b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
323c0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
323d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
323e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
323f0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
32400 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
32410 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
32420 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
32430 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
32440 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
32450 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
32460 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
32470 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
32480 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
32490 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
324a0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
324b0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
324c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
324d0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
324e0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
324f0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
32500 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
32510 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
32520 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
32530 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
32540 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32550 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
32560 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
32570 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
32580 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
32590 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
325a0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
325b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
325c0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
325d0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
325e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
325f0 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
32600 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
32610 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
32620 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
32630 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
32640 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
32650 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
32660 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
32670 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
32680 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f            1    /
32690 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33  * IMP: R-37514-3
326a0 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20  5566 */.#define 
326b0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
326c0 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d        2    /* IM
326d0 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37  P: R-03371-37637
326e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
326f0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
32700 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    3    /* IMP: R
32710 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a  -51971-34154 */.
32720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32730 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
32740 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
32750 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
32760 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
32770 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
32780 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
32790 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
327a0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
327b0 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
327c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
327d0 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
327e0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
327f0 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
32800 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
32810 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
32820 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
32830 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
32840 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
32850 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
32860 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
32870 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
32880 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
32890 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
328a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
328b0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
328c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
328d0 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
328e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
328f0 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
32900 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
32910 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
32920 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
32930 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
32940 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
32950 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
32960 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
32970 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
32980 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
32990 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
329a0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
329b0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
329c0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
329d0 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
329e0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
329f0 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
32a00 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
32a10 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
32a20 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
32a30 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
32a40 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
32a50 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
32a60 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
32a70 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
32a80 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
32a90 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
32aa0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
32ab0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
32ac0 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
32ad0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
32ae0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32af0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
32b00 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
32b10 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
32b20 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
32b30 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
32b40 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
32b50 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
32b60 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
32b70 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
32b80 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
32b90 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
32ba0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
32bb0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
32bc0 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
32bd0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
32be0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
32bf0 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
32c00 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
32c10 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
32c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32c30 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
32c40 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
32c50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
32c60 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
32c70 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
32c80 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
32c90 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
32ca0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
32cb0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
32cc0 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
32cd0 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
32ce0 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
32cf0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
32d00 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
32d10 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
32d20 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
32d30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
32d40 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
32d50 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
32d60 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
32d70 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
32d80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
32d90 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
32da0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
32db0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
32dc0 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
32dd0 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
32de0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
32df0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
32e00 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
32e10 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
32e20 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
32e30 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
32e40 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
32e50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32e60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
32e70 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
32e80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32e90 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
32ea0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
32eb0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
32ec0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32ed0 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
32ee0 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
32ef0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
32f00 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
32f10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
32f20 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
32f30 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
32f40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32f50 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
32f60 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
32f70 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
32f80 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
32f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
32fa0 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
32fb0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
32fc0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
32fd0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
32fe0 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
32ff0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
33000 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
33010 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
33020 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75  t that these rou
33030 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
33040 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
33050 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
33060 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
33070 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
33080 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
33090 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
330a0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
330b0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
330c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
330d0 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
330e0 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
330f0 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
33100 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
33110 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
33120 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
33130 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
33140 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
33150 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33160 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
33170 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
33180 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
33190 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
331a0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
331b0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
331c0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
331d0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
331e0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
331f0 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
33200 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
33210 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
33220 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
33230 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
33240 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
33250 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
33260 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
33270 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
33280 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
33290 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
332a0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
332b0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
332c0 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
332d0 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
332e0 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
332f0 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
33300 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
33310 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
33320 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
33330 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
33340 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
33350 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
33360 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
33370 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
33380 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
33390 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
333a0 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
333b0 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
333c0 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
333d0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
333e0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
333f0 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
33400 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
33410 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
33420 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
33430 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
33440 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
33450 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
33460 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33470 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
33480 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
33490 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
334a0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
334b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
334c0 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
334d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
334e0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
334f0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
33500 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
33510 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
33520 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
33530 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
33540 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
33550 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
33560 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
33570 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
33580 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
33590 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
335a0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
335b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
335c0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
335d0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
335e0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
335f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33600 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
33610 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
33620 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
33630 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
33640 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
33650 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
33660 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
33670 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33680 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
33690 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
336a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
336b0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
336c0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
336d0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
336e0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
336f0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
33700 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
33710 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
33720 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
33730 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
33740 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
33750 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
33760 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
33770 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
33780 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
33790 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
337a0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
337b0 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
337c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
337d0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
337e0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
337f0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
33800 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
33810 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
33820 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
33830 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
33840 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
33850 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
33860 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
33870 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
33880 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
33890 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
338a0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
338b0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
338c0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
338d0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
338e0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
338f0 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
33900 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
33910 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
33920 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
33930 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
33940 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
33950 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
33960 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
33970 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
33980 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
33990 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
339a0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
339b0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
339c0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
339d0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
339e0 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
339f0 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
33a00 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
33a10 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
33a20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
33a30 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
33a40 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
33a50 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
33a60 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
33a70 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
33a80 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
33a90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
33aa0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
33ab0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
33ac0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
33ad0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
33ae0 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
33af0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
33b00 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
33b10 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
33b20 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
33b30 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
33b40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33b50 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
33b60 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
33b70 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
33b80 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e  pointer .** when
33b90 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66   first called if
33ba0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
33bb0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
33bc0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a   or if a memory.
33bd0 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ** allocate erro
33be0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
33bf0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
33c00 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
33c10 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
33c20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
33c30 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
33c40 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
33c50 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
33c60 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
33c70 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
33c80 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
33c90 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
33ca0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
33cb0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
33cc0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
33cd0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
33ce0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
33cf0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
33d00 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
33d10 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e  ation.)^  Within
33d20 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
33d30 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74  back, it is cust
33d40 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20  omary to set.** 
33d50 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20  N=0 in calls to 
33d60 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33d70 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73  e_context(C,N) s
33d80 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f  o that no .** po
33d90 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61  intless memory a
33da0 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72  llocations occur
33db0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
33dc0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
33dd0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
33de0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
33df0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33e00 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
33e10 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
33e20 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
33e30 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
33e40 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
33e50 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
33e60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
33e70 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
33e80 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
33e90 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
33ea0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
33eb0 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
33ec0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
33ed0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
33ee0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
33ef0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
33f00 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
33f10 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
33f20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
33f30 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
33f40 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
33f50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
33f60 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
33f70 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
33f80 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
33f90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
33fa0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
33fb0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
33fc0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
33fd0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
33fe0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
33ff0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
34000 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
34010 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
34020 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
34030 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
34040 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
34050 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
34060 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34070 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
34080 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34090 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
340a0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
340b0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
340c0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
340d0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
340e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
340f0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
34100 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
34110 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
34120 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
34130 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34140 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
34150 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
34160 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
34170 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34180 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
34190 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
341a0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
341b0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
341c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
341d0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
341e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
341f0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
34200 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
34210 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34220 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
34230 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
34240 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
34250 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
34260 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
34270 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
34280 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
34290 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
342a0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
342b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
342c0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
342d0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
342e0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
342f0 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
34300 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
34310 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
34320 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
34330 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
34340 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
34350 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67  d by (non-aggreg
34360 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ate) SQL functio
34370 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
34380 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
34390 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
343a0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
343b0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
343c0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
343d0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
343e0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
343f0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
34400 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
34410 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
34420 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
34430 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
34440 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
34450 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f   An example.** o
34460 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67  f where this mig
34470 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20  ht be useful is 
34480 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70  in a regular-exp
34490 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67  ression matching
344a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
344b0 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
344c0 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
344d0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
344e0 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   be stored as.**
344f0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
34500 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61  ated with the pa
34510 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a  ttern string.  .
34520 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20  ** Then as long 
34530 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73  as the pattern s
34540 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68  tring remains th
34550 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63  e same,.** the c
34560 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
34570 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
34580 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
34590 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
345a0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
345b0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
345c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
345d0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
345e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
345f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
34600 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
34610 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
34620 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34630 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
34640 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
34650 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
34660 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34670 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
34680 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  If there is no m
34690 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
346a0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66  iated with the f
346b0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
346c0 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67  , this sqlite3_g
346d0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
346e0 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e  erface.** return
346f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
34700 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34710 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34720 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66  (C,N,P,X) interf
34730 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d  ace saves P as m
34740 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
34750 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
34760 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34770 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34780 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65  tion.  ^Subseque
34790 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
347a0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
347b0 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50  ta(C,N) return P
347c0 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72   from the most r
347d0 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33  ecent.** sqlite3
347e0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
347f0 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68  ,P,X) call if th
34800 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74  e metadata is st
34810 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20  ill valid or.** 
34820 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61  NULL if the meta
34830 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69  data has been di
34840 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74  scarded..** ^Aft
34850 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20  er each call to 
34860 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34870 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65  ata(C,N,P,X) whe
34880 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  re X is not NULL
34890 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  ,.** SQLite will
348a0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
348b0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
348c0 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72  X with parameter
348d0 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e   P exactly.** on
348e0 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74  ce, when the met
348f0 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64  adata is discard
34900 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  ed..** SQLite is
34910 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64   free to discard
34920 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74   the metadata at
34930 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75   any time, inclu
34940 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  ding: <ul>.** <l
34950 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  i> when the corr
34960 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
34970 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
34980 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  nges, or.** <li>
34990 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   when [sqlite3_r
349a0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
349b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
349c0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  is called for th
349d0 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74  e.**      SQL st
349e0 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c  atement, or.** <
349f0 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33  li> when sqlite3
34a00 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
34a10 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20  s invoked again 
34a20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61  on the same para
34a30 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  meter, or.** <li
34a40 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69  > during the ori
34a50 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65  ginal sqlite3_se
34a60 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c  t_auxdata() call
34a70 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a   when a memory .
34a80 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69  **      allocati
34a90 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  on error occurs.
34aa0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e   </ul>)^.**.** N
34ab0 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c  ote the last bul
34ac0 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61  let in particula
34ad0 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74  r.  The destruct
34ae0 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69  or X in .** sqli
34af0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34b00 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62  C,N,P,X) might b
34b10 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61  e called immedia
34b20 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65  tely, before the
34b30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
34b40 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
34b50 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73  ace even returns
34b60 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33  .  Hence sqlite3
34b70 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a  _set_auxdata().*
34b80 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c  * should be call
34b90 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20  ed near the end 
34ba0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
34bb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61  implementation a
34bc0 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  nd the.** functi
34bd0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
34be0 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b  n should not mak
34bf0 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61  e any use of P a
34c00 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  fter.** sqlite3_
34c10 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61  set_auxdata() ha
34c20 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a  s been called..*
34c30 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
34c40 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
34c50 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
34c60 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
34c70 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   for.** function
34c80 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
34c90 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   are compile-tim
34ca0 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63  e constants, inc
34cb0 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a  luding literal.*
34cc0 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61  * values and [pa
34cd0 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78  rameters] and ex
34ce0 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73  pressions compos
34cf0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
34d00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
34d10 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
34d20 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
34d30 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
34d40 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
34d50 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
34d60 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
34d70 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
34d80 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
34d90 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
34da0 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
34db0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
34dc0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
34dd0 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
34de0 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
34df0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
34e00 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
34e10 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
34e20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
34e30 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
34e40 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
34e50 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
34e60 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
34e70 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
34e80 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
34e90 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
34ea0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
34eb0 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
34ec0 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
34ed0 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
34ee0 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
34ef0 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
34f00 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
34f10 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
34f20 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
34f30 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
34f40 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
34f50 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
34f60 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
34f70 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
34f80 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
34f90 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
34fa0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
34fb0 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
34fc0 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
34fd0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
34fe0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
34ff0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
35000 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
35010 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
35020 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
35030 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
35040 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
35050 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  lers..*/.typedef
35060 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
35070 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
35080 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
35090 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
350a0 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
350b0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
350c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
350d0 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
350e0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
350f0 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
35100 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
35110 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
35120 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
35130 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
35140 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
35150 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
35160 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
35170 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
35180 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
35190 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
351a0 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
351b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
351c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
351d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
351e0 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
351f0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
35200 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
35210 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
35220 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
35230 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
35240 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
35250 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
35260 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
35270 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
35280 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
35290 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
352a0 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
352b0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
352c0 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
352d0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
352e0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
352f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35300 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
35310 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
35320 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
35330 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35340 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
35350 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
35360 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
35370 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
35380 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
35390 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
353a0 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
353b0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
353c0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
353d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
353e0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
353f0 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
35400 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
35410 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
35420 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35430 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
35440 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
35450 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
35460 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
35470 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
35480 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
35490 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
354a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
354b0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
354c0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
354d0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
354e0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
354f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35500 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
35510 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
35520 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
35530 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
35540 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35550 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35560 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
35570 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
35580 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
35590 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
355a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
355b0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
355c0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
355d0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
355e0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
355f0 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
35600 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
35610 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
35620 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
35630 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
35640 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
35650 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
35660 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
35670 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
35680 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
35690 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
356a0 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
356b0 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
356c0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
356d0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
356e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
356f0 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
35700 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
35710 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
35720 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
35730 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
35740 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
35750 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35760 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
35770 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
35780 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
35790 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
357a0 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
357b0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
357c0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
357d0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
357e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
357f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35800 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
35810 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
35820 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
35830 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
35840 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
35850 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
35860 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
35870 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
35880 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
35890 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
358a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
358b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
358c0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
358d0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
358e0 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
358f0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
35900 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
35910 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
35920 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
35930 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
35940 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
35950 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
35960 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
35970 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
35980 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
35990 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
359a0 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
359b0 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
359c0 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
359d0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
359e0 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
359f0 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
35a00 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
35a10 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
35a20 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
35a30 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
35a40 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
35a50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35a60 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
35a70 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35a80 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
35a90 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
35aa0 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
35ab0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35ac0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
35ad0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
35ae0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
35af0 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
35b00 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
35b10 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
35b20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
35b30 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
35b40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35b50 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
35b60 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
35b70 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
35b80 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
35b90 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
35ba0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
35bb0 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
35bc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35bd0 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72  sult_int() inter
35be0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
35bf0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
35c00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35c10 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35c20 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  n to be the 32-b
35c30 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
35c40 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
35c50 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
35c60 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ment..** ^The sq
35c70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
35c80 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
35c90 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
35ca0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
35cb0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35cc0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
35cd0 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
35ce0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
35cf0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
35d00 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
35d10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35d20 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
35d30 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
35d40 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
35d50 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
35d60 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35d70 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
35d80 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
35d90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35da0 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  xt(), sqlite3_re
35db0 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a  sult_text16(),.*
35dc0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
35dd0 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
35de0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35df0 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
35e00 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
35e10 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35e20 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35e30 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35e40 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
35e50 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
35e60 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
35e70 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
35e80 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
35e90 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
35ea0 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
35eb0 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
35ec0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
35ed0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
35ee0 65 73 75 6c 74 5f 74 65 78 74 36 34 28 29 20 69  esult_text64() i
35ef0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
35f00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
35f10 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74  f an.** applicat
35f20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35f30 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 74 65 78  tion to be a tex
35f40 74 20 73 74 72 69 6e 67 20 69 6e 20 61 6e 20 65  t string in an e
35f50 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69  ncoding.** speci
35f60 66 69 65 64 20 62 79 20 74 68 65 20 66 69 66 74  fied by the fift
35f70 68 20 28 61 6e 64 20 6c 61 73 74 29 20 70 61 72  h (and last) par
35f80 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 6d 75  ameter, which mu
35f90 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20  st be one.** of 
35fa0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
35fb0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b  SQLITE_UTF16], [
35fc0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
35fd0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
35fe0 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  6LE]..** ^SQLite
35ff0 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
36000 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
36010 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
36020 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
36030 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
36040 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36050 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
36060 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
36070 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
36080 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36090 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
360a0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
360b0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
360c0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
360d0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
360e0 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
360f0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
36100 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
36110 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
36120 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
36130 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
36140 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
36150 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
36160 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
36170 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
36180 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
36190 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
361a0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
361b0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
361c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
361d0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
361e0 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20  result.  If the 
361f0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
36200 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
36210 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62  hen it.** must b
36220 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
36230 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e  t into the strin
36240 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  g where the NUL 
36250 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
36260 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68  .** appear if th
36270 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e  e string where N
36280 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  UL terminated.  
36290 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
362a0 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69  cters occur.** i
362b0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20  n the string at 
362c0 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68  a byte offset th
362d0 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  at is less than 
362e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
362f0 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65   3rd.** paramete
36300 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  r, then the resu
36310 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c  lting string wil
36320 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  l contain embedd
36330 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a  ed NULs and the.
36340 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  ** result of exp
36350 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69  ressions operati
36360 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69  ng on strings wi
36370 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
36380 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
36390 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
363a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
363b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
363c0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
363d0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
363e0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
363f0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
36400 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
36410 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
36420 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
36430 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
36440 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
36450 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
36460 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
36470 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
36480 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
36490 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
364a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
364b0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
364c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
364d0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
364e0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
364f0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
36500 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
36510 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
36520 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
36530 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
36540 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
36550 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
36560 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
36570 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
36580 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
36590 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
365a0 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
365b0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
365c0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
365d0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
365e0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
365f0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
36600 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
36610 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
36620 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
36630 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
36640 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
36650 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
36660 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
36670 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
36680 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
36690 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
366a0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
366b0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
366c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
366d0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
366e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
366f0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
36700 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36710 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36720 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
36730 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
36740 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36750 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
36760 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
36770 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
36780 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36790 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
367a0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
367b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
367c0 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
367d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
367e0 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
367f0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
36800 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
36810 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
36820 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
36830 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
36840 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
36850 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
36860 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
36870 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
36880 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
36890 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
368a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
368b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
368c0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
368d0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
368e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
368f0 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
36900 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
36910 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
36920 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
36930 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
36940 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
36950 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
36960 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
36970 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
36980 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36990 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
369a0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
369b0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
369c0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
369d0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
369e0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
369f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
36a00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36a10 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
36a20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
36a30 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36a40 65 73 75 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c  esult_blob64(sql
36a50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f  ite3_context*,co
36a60 6e 73 74 20 76 6f 69 64 2a 2c 0a 20 20 20 20 20  nst void*,.     
36a70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36a80 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 75 69        sqlite3_ui
36a90 6e 74 36 34 2c 76 6f 69 64 28 2a 29 28 76 6f 69  nt64,void(*)(voi
36aa0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
36ab0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
36ac0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36ad0 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
36ae0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36af0 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
36b00 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
36b10 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
36b20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36b30 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
36b40 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
36b50 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
36b60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36b70 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
36b80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
36b90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36ba0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
36bb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36bc0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36bd0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
36be0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
36bf0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
36c00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
36c10 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
36c20 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
36c30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
36c40 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
36c50 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
36c60 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
36c70 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
36c80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
36c90 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36ca0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
36cb0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
36cc0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
36cd0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
36ce0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36cf0 75 6c 74 5f 74 65 78 74 36 34 28 73 71 6c 69 74  ult_text64(sqlit
36d00 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
36d10 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
36d20 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
36d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36d40 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
36d50 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
36d60 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 76 6f 69  r encoding);.voi
36d70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36d80 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
36d90 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
36da0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
36db0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
36dc0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36dd0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
36de0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
36df0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
36e00 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
36e10 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36e20 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
36e30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
36e40 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
36e50 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
36e60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36e70 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
36e80 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
36e90 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
36ea0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36eb0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
36ec0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
36ed0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36ee0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
36ef0 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
36f00 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
36f10 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
36f20 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
36f30 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
36f40 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
36f50 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
36f60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
36f70 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
36f80 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
36f90 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
36fa0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
36fb0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
36fc0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
36fd0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
36fe0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
36ff0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
37000 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
37010 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
37020 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
37030 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
37040 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
37050 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
37060 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
37070 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
37080 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
37090 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
370a0 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
370b0 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
370c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
370d0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
370e0 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
370f0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
37100 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
37110 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
37120 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
37130 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
37140 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
37150 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
37160 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
37170 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
37180 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
37190 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
371a0 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
371b0 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
371c0 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
371d0 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
371e0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
371f0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37200 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
37210 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
37220 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
37230 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
37240 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
37250 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
37260 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
37270 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
37280 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
37290 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
372a0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
372b0 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
372c0 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
372d0 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
372e0 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
372f0 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
37300 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
37310 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
37320 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
37330 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
37340 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
37350 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
37360 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
37370 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37380 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
37390 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
373a0 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
373b0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
373c0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
373d0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
373e0 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
373f0 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
37400 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
37410 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
37420 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
37430 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
37440 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
37450 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
37460 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
37470 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
37480 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
37490 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
374a0 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
374b0 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
374c0 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
374d0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
374e0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
374f0 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
37500 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
37510 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
37520 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
37530 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
37540 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
37550 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
37560 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
37570 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
37580 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
37590 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
375a0 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
375b0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
375c0 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
375d0 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
375e0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
375f0 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
37600 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
37610 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
37620 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
37630 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
37640 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
37650 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
37660 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
37670 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
37680 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
37690 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
376a0 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
376b0 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
376c0 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
376d0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
376e0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
376f0 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
37700 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
37710 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
37720 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
37730 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
37740 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
37750 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
37760 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
37770 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
37780 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
37790 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
377a0 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
377b0 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
377c0 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
377d0 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
377e0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
377f0 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
37800 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
37810 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
37820 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
37830 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
37840 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
37850 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
37860 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
37870 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
37880 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
37890 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
378a0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
378b0 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
378c0 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
378d0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
378e0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
378f0 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
37900 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
37910 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
37920 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37930 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
37940 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
37950 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
37960 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
37970 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
37980 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
37990 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
379a0 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
379b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
379c0 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
379d0 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
379e0 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
379f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
37a00 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
37a10 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
37a20 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
37a30 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
37a40 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
37a50 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
37a60 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
37a70 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
37a80 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
37a90 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
37aa0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
37ab0 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
37ac0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
37ad0 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
37ae0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
37af0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
37b00 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
37b10 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
37b20 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
37b30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37b40 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
37b50 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
37b60 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
37b70 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
37b80 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37b90 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
37ba0 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
37bb0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
37bc0 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
37bd0 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
37be0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
37bf0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
37c00 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
37c10 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
37c20 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
37c30 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
37c40 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
37c50 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
37c60 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
37c70 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
37c80 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
37c90 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
37ca0 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
37cb0 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
37cc0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
37cd0 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
37ce0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
37cf0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
37d00 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
37d10 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
37d20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
37d30 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
37d40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
37d50 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
37d60 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37d70 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
37d80 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
37d90 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
37da0 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
37db0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
37dc0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
37dd0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
37de0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
37df0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
37e00 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
37e10 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
37e20 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
37e30 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
37e40 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
37e50 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
37e60 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
37e70 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
37e80 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
37e90 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
37ea0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37eb0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
37ec0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
37ed0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
37ee0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
37ef0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
37f00 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
37f10 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
37f20 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
37f30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37f40 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
37f50 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
37f60 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
37f70 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
37f80 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
37f90 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
37fa0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
37fb0 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
37fc0 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
37fd0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
37fe0 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
37ff0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
38000 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
38010 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
38020 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
38030 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
38040 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
38050 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
38060 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
38070 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
38080 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
38090 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
380a0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
380b0 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
380c0 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
380d0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
380e0 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
380f0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
38100 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
38110 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
38120 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
38130 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
38140 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
38150 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
38160 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
38170 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
38180 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
38190 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
381a0 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
381b0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
381c0 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
381d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
381e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
381f0 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
38200 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
38210 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
38220 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
38230 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
38240 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
38250 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
38260 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
38270 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
38280 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
38290 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
382a0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
382b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
382c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
382d0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
382e0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
382f0 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
38300 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
38310 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
38320 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
38330 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
38340 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
38350 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
38360 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
38370 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
38380 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
38390 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
383a0 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
383b0 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
383c0 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
383d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
383e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
383f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
38400 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
38410 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
38420 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
38430 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
38440 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
38450 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
38460 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
38470 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
38480 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
38490 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
384a0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
384b0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
384c0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
384d0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
384e0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
384f0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
38500 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
38510 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
38520 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
38530 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
38540 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
38550 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
38560 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
38570 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
38580 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
38590 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
385a0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
385b0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
385c0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
385d0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
385e0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
385f0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
38600 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
38610 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
38620 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
38630 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
38640 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
38650 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
38660 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
38670 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  y */.);.int sqli
38680 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20 73 71  te3_key_v2(.  sq
38690 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
386a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
386b0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
386c0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
386d0 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
386e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61             /* Na
386f0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
38700 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  se */.  const vo
38710 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
38720 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
38730 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
38740 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
38750 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
38760 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
38770 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
38780 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
38790 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
387a0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
387b0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
387c0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
387d0 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
387e0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
387f0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
38800 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
38810 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20